.. image:: imgs/icon_gettinginvolved.png :align: right :alt: Saefty first when breaking out the power tools. ============================= Getting involved ============================= There are many ways to help out, and they don't all involve coding. ----------------------------- Translations ----------------------------- Sprechen Sie Deutsch? Awesome! I've been getting my head around the whole translation bit (English monoglot I'm afraid), and as a result there has been a lot of churn in the translations. So what are you waiting for? Speak some other language? Take a look at https://translations.launchpad.net/terminator because you might just be the speaker that we're looking for. ----------------------------- Improve icons/artwork ----------------------------- OK, so while the main icon contributed by Cory Kontros is really good, my hacks of it are... not so good. I'm no artist, but I do appreciate them. So if you think you could apply some polish and a cohesive design to this manuals page header images, please, give it a go. It may only be to take the existing icon and to make it suck less. The only thing I would ask is that you maintain the main icon as a base like I have done. ----------------------------- Terminator action shots ----------------------------- This one's just for "PR" purposes. I want to see famous/awesome people kicking ass *and* chewing bubble-gum with Terminator in the mix. If you spot it in a TV show, movie, or a news article I want to know. Maybe you're even the famous/awesome person, in which case drop me a note. It will warm the cockles of my heart to know that Terminator made life easier for people who do the really important stuff like discovering new particles (CERN? Hello?), boldly going (NASA? Come in Houston), or wrangle 2 more frames per second from Half-Life 3 (Valve? Confirmed?) Here's the ones I've spotted and noted (I've seen quite a few others previously, but never thought to note them) - `MindMaze`_ - VR / mind-reading. Visible in the background of the video, and in an image lower down the page. (The Verge) - `Dual Universe`_ - Sci-Fi MMORPG Visible at 17:40 of the pitch video. (KickStarter) .. _MindMaze: http://www.theverge.com/2015/3/3/8136405/mind-maze-mind-leap-thought-reading-virtual-reality-headset .. _Dual Universe: https://www.kickstarter.com/projects/1949863330/dual-universe-civilization-building-sci-fi-mmorpg ----------------------------- Manual updates ----------------------------- This manual is a new endeavour to fully document all the nooks and crannies of Terminator. As such, there may be things that are missing, incorrect, not explained clearly, or need expanding. Suggestions, or updates are welcome. I had a little exposure at work to Sphinx, so I thought I'd dig in a bit deeper and learn a bit about it. So far I'm happy enough, so till further notice this manual will remain in this format. If you're feeling like a loquacious polyglot you could attempt to translate the whole manual. So far I haven't tested it, but in principle, just do an export of the manual-gtk3 branch in Launchpad to a folder ``manual-gtk3-``, where ```` is the i18n language code. This is usually just the two or three letters of the language code, but sometimes has the region too... Or something else entirely in a couple of cases. A couple of examples:: pt - Portugese pt_BR - Brazilian Portugese ca - Catalan ca@valencia - Catalan (Dialect specific to Valencia?) Then just translate away, and take new screen grabs to replace the British English ones I've done. If someone was to make a serious effort to translate the manual, I'm sure we can get it included. .. note:: If there are any Americans offended by correct spelling, they are more than welcome to create an Americanised version, and I'll relegate it to the en_US folder. The default will remain British English. As there is only one language available, the Help shortcut will by default open:: http://terminator-gtk3.readthedocs.io/en/latest/index.html The specifics of how readthedocs.io handle multiple languages are still a little hazy, but as I understand it uses the http headers passed by your browser, and directs you to the appropriate URL, for example:: http://terminator-gtk3.readthedocs.io/de/latest/index.html In order to build the html for the manual, you must have sphinx and the sphinx_rtd_theme package installed. Ideally you will be using a distro with these packages available. An example would be Ubuntu 16.04 LTS:: sudo apt-get install python-sphinx python-sphinx-rtd-theme This will take care of installing sphinx, the theme and it's dependencies. Once a manual has a reasonable amount of translation we can look into adding it to the readthedocs.io website so it integrates properly. .. warning:: This section may need updating if we do reach the point of adding another manual. It is at this point we will have to figure out the details of adding the translated manuals, and getting the user to the correct document. ----------------------------- Testing ----------------------------- Just use it, explore the features, and complain when they don't work. We actually have quite a lots of outstanding issues, and in many cases I can't reproduce due to either lack of info, differences in environment, lack of information, or because the bug is so old the original raiser has moved on and not available for questions. I'm particularly interested in cases where I can't even see that something is an issue, such as: - *Right-to-Left* - I can force Terminator to Arabic, and everything flips around, but I have no idea if it looks "right" to a native speaker. Frankly it just looks *weird!* - *HighContrast* - Again, I can switch to it, but perhaps I'm not appreciating the needs of that group. - *Accessibility* - People using only a keyboard, or only a mouse, on-screen keyboards, text-to-speech, speech-to-text, and so on. ----------------------------- Bugs ----------------------------- Bugs (and feature requests) are raised and dealt with in the Launchpad `bugs`_ page. .. _bugs: https://bugs.launchpad.net/terminator - **Fixing** - OK, so yeah, this is coding. - **Reproduce and improving** - Sometimes bugs are lacking info to reproduce, or my system is too different. Or perhaps the original poster has moved on because we haven't fixed their pet peeve fast enough. - **Triaging** - It's one of the less glamorous jobs, but someone's gotta do it. Shepherd bugs to the point where it has a priority, a milestone, reproduction steps, confirmation, submitted patches validated, and so on. - **Raising** - If you have searched and cannot find your bug, you can raise a new one. Feature requests are initially raised as bugs, and if it passes the rather undefined criteria, it will be marked as a **wishlist** item. Bug handling ^^^^^^^^^^^^ I have had one person (possibly others) who are hesitant to use the status' because they've been "told off" by the developers of other projects, and people/projects are often different in how they want to handle bugs. So, with that in mind, let me present my idea of how a bug should be handled. First a pretty picture: .. image:: imgs/launchpad_bugflow.png :scale: 100% :align: center So, the darker blue states are the ones available in Launchpad that can be manually set. The two marked with a red outline require bug supervisor role to set, which means a member of the Terminator team. The pale blue states are ones that I personally feel should be there, but are missing. I'll explain my intention with those in the appropriate sections below. The grey state is set automatically only, and cannot be set by anyone. Initial/New ~~~~~~~~~~~ When you the user create a bug it goes into **New**. If another user clicks the *This bug affects you* link, this gets moved to **Confirmed**. Investigation ~~~~~~~~~~~~~ If I (or indeed someone else) go to a *New* or *Confirmed* bug, and are unable to reproduce it then it will be marked **Incomplete**, and someone (preferably the original raiser, but it can be someone else affected) needs to revisit and provide the requested additional info. Ideally when that is added there would be a *New Info* (or similar) state that the user would set the bug to, and then the dashed line would be taken. Because we don't have this state, we "skip" straight through and abuse the **Confirmed** state. Set the bug (back) to **Confirmed**, and assign the official tag *new-info*. Once the ticket is reviewed the tag will be removed, and a new state assigned, possibly even *Incomplete* again. Note that I am aware of the two *Incomplete* options for with and without response, but the way it works is unclear, and I can't switch between the two myself, and it is not clear when Launchpad switches it. So, I'll be ignoring them and treating *Incomplete* as a single state. Acceptance ~~~~~~~~~~ At this point the bug should provide enough information to be reproducible. Only a supervisor can set an issue to **Triaged**. This state says, "Yes, the information provided either permits me to reproduce myself, or see what went wrong from provided logs, config, etc." Typically they go here when I don't have the time to start working on an immediate fix. Alternatively I (or anyone) could start working on a bug. Ideally the issue should be set to **In Progress**, and assigned to the person picking it up. That way, two people don't work on the same issue. Sometimes, for trivial or interesting bugs, they might get looked at and fixed so fast that they skip all *Acceptance* categories, and go straight to one of the *Resolved* states. Resolved ~~~~~~~~ **Fix Committed** is for when a fix is pushed to the main Launchpad bazaar repository and typically I do this. If you create a contribution via a branch, and commit to your branch, do not set to this yourself. Instead associate the bug with the branch, and request a merge. When I do the merge I will also set the bug to *Fix Committed*. An **Invalid** bug is usually because the user didn't understand something, or it is in fact a support request. Only a bug supervisor can set an issue to **Won't Fix**. It is the supervisors way of ending the discussion when it is felt that a bug does not fit the projects plans, but someone can't `let it go`_. **Opinion** is typically when the user and I have a different expectation about behaviour or a new feature, or I think that something being proposed would actually be a negative for Terminator. Unlike *Won't Fix*, this can still be discussed within the ticket. **Not Responsible** is our second missing virtual state. For me this is when, for example, an issue actually resides in *libvte*, or *GTK*. Again, there is a new official tag *not-responsible*, and the bug will actually end up set to *Invalid*. The final virtual state is **No Action**, which is for various reasons. Sometimes other work has resolved an issue already, or the user was using an old version, and the fix is already in trunk or released. Again there is a new official tag *no-action*. These will then be put in one of the following: *Invalid*, *Fix Committed*, or *Fix Released*, depending on circumstance. Our last Resolved state is the automatically set **Expired** one. This can only be set by Launchpad when a bug is set to *Incomplete*, and has been idle for 60 days. This is actually an on/off feature that is set by the project, and applies project-wide. Currently this is not active for Terminator bugs, but one day (when I get caught up, ha!) I might choose to turn this on. Available ~~~~~~~~~ The last state is **Fix Released**, indicating that there has been a release containing a fix to the issue. Of course this flow and states are not set in stone. A bug can be brought out of *Expired* if necessary. Or back from *In Progress* to *Confirmed* or *Triaged* if the assignee decides to stop working on the bug for some reason. .. _let it go: https://www.youtube.com/watch?v=L0MK7qz13bU#t=1m05s ----------------------------- Plugins ----------------------------- Ahem... Yeah... More coding... Some :ref:`plugins` may have room for improvement, or perhaps you have an idea for a neat plugin no-one else has done. ----------------------------- Main Application Development ----------------------------- Oh come on... Coding? Again! I see lots of people say how Terminator is really good, and it is, but like anything, it could be better! To give an idea, as of March 2017, revision 1760, there are around 100 `wishlist items`_. .. note:: Just because an item is marked as wishlist, it doesn't mean that a great deal of thought has been put into the appropriateness of the idea on my side. It may be impossible, or not a good fit, or just plain bat-sh!t crazy. If you want to pick up a wishlist item that looks like a lot of work (especially if it makes fundamental changes to the Terminator ethos) it's probably best to check first that your approach is good, and has a realistic chance of being merged. Some of these wishlist items are also in my own text file of "Things to do" / "Big bag of crazy", which as of March 2017, revision 1760, looks like this:: Enhancements which may or may not have a wishlist item ====================================================== Completely new features Add libunity quicklist of saved layouts https://wiki.ubuntu.com/Unity/LauncherAPI#Python_Example http://www.techques.com/question/24-64436/Refreshing-of-Dynamic-Quicklist-doesn%27t-work-after-initialization http://people.canonical.com/~dpm/api/devel/GIR/python/Unity-3.0.html Possibly use the progress bar and or counter for something too. Add an appindicator menu for launching sessions. If we can figure out how to do arbritrary highlighting, perhaps we can get a "highlight differences" mode like used to exist in ClusTerm. This could also be limted to highlighting diffs between those in the same group. Synchronised scroll based on groups Triggers (actions) based on regex for received text A "swap" mode for drag and drop Encrypted dumping/logging to disk Remotinator commands to modify debug level / class / funcs, and switch trace on/off Allow custom commands to only show on particular profiles Search Might be able to missuse the ClusTerm method of overwriting to "highlight" (gtk2 only) Layouts Layout Launcher Could bind the shortcut as a global toggle to hide show Could save window position/size hidden status always on top pin to visible workspace Layout needs to save/load more settings Per layout? Group mode status (all, group, off) Split to this group Autoclean groups Per window always on top pin to visible workspace Per tab Per terminal Store the custom command and working directory when we load a layout, so making small changes and saving doesn't lose everything. It could be possible to detect the current command and working directory with psutil, but could be tricky. (i.e. do we ignore bash?) A per layout "save on exit" option to always remember last setup/positions etc. Probably requires above to be done first. A per layout shortcut launch hotkey Missing shortcuts: Just shortcut: Context menu (in addition to Windows menu button - not always available on all keyboards) Group menu Open preferences Change group name Toggle titlebar visibility Equalise the splitters (siblings/siblings+children/siblings+parents,all) Zoom +receiver in/out/reset Zoom all in/out/reset New code: Open a shortcut help overlay (Ctrl-F1?) Insert tab text, titlebar text, group name value into terminal(s) Last terminal / tab / window(again to jump back to original) #1440049 Limit broadcast group/all to current tab / window (toggle) Broadcast temporarily off when maximised or zoomed to single term (toggle) Titlebar Add large action/status icons for when titlebar is bigger and/or HiPDI Improve the look/spacing of the titlebar, i.e. the spacing around/between elements Tabs right-click menu replicating GNOME-Terminals (move left/right, close, rename) Menus Add accelerators (i.e. "Shift+Ctr+O") might look too cluttered. Preferences Profiles Add preselection to the profile tab Add filter to font selector to only show fixed width fonts Layouts Have changing widgets depending on what is selected in the tree Terminal title editable Button in prefs to duplicate a layout Ordering in list Working directory - add dialog too, see http://stackoverflow.com/questions/10868167/make-filechooserdialog-allow-user-to-select-a-folder-directory Keybindings Add a list of the default keybindings to the Preferences -> Keybindings window? Option for close_button_on_tab in prefs. (needs tab right-click menu first Option to rebalance siblings on a split (don't think children or ancestors make sense) Figure out how to get the tree view to jump to selected row for prefseditor Plugins Give plugins ability to register shortcuts Custom Commands is blocking, perhaps make non-blocking Drag and Drop LP#0768520: Terminal without target opens new window LP#1471009: Tab to different/new window depending on target Major architectural Improve DBus interface, add coordination between sessions, i.e.: multiple DBus ports? register them with a master DBus session, be able to query these, etc be able to drive them more with command line commands, and not just from within own shell Remotinator improvements Abstract out the session/layout allowing multiple logical layouts in the same process to reduce resource used This is a big piece of work, as a lot of the Terminator class would need seperating out. Hide window should find the last focussed window and hide that. Second hit unhides and focusses it Add a power hide to hide all of shortcut bound instances windows Use the dbus if available to hide the current active window, then unhide it on second shortcut press If the dbus is available: The hide will go to the focussed instance, instead of the first to grab the shortcut Add a super power hide to hide all Terminator windows In both cases a second shortcut unhides whatever was hidden Split with command / Inherit command/workdir/groups etc Somehow make Layout Launcher, Preferences, & poss. Custom Commands singleton/borg (possibly use dbus) When in zoomed/maximised mode Perhaps the menu could contain a quick switch sub menu, rather than having to Restore, right-click, maximise Shortcuts for next/prev,up/down/left/right, etc. How should they behave All non main windows to be changed to glade files For me the two different sets of next/prev shortcuts are a bit of a mystery. Let window title = terminal titlebar - perhaps other combos. Some kind of %T %G %W substitution? So as you can see, still lots of room for improvements, and plenty of ideas if you are trying to find small starter tasks. .. _wishlist items: https://bugs.launchpad.net/terminator/+bugs?field.searchtext=&orderby=-importance&search=Search&field.status%3Alist=NEW&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.importance%3Alist=WISHLIST&assignee_option=any&field.assignee=&field.bug_reporter=&field.bug_commenter=&field.subscriber=&field.structural_subscriber=&field.tag=&field.tags_combinator=ANY&field.has_cve.used=&field.omit_dupes.used=&field.omit_dupes=on&field.affects_me.used=&field.has_patch.used=&field.has_branches.used=&field.has_branches=on&field.has_no_branches.used=&field.has_no_branches=on&field.has_blueprints.used=&field.has_blueprints=on&field.has_no_blueprints.used=&field.has_no_blueprints=on ----------------------------- GTK2 Maintenance ----------------------------- The GTK2 version of Terminator has gone into deprecated mode as far as I'm concerned. If someone wants to pick up the back-porting of fixes they can contact me, and I'll give them commit access on the GTK2 branch. It is better that any focus I can spare is spent on the GTK3 version. ----------------------------- GTK3 Port ----------------------------- Last coding one, I promise! After some sterling work by Egmont Koblinger, one of the VTE developers, he came up with a very large patch for rudimentary GTK3 support. A number of things were incomplete or broken, but it got it far enough along that it was no longer an insurmountable cliff face. After that I resolved to port fixes and features between the two versions. For a time I managed this, but it got to the point where the GTK3 port was better and more stable than the old GTK2 code, due to VTE and GTK improvements that added features, and seems to have fixed many (if not all) of the segfault crashes that would happen within the GTK2 libraries. The port is pretty much complete. I *hope* we've fixed any regressions and critical issues. There are a few minor tasks that don't seem to be urgent as far as I can see listed below. Feel free to look into these. For the record, as of March 2017, with the `gtk3 branch`_ at revision around 1760, these are the outstanding items:: Outstanding GTK3 port tasks/items/reviews/reimplementations etc. ================================================================ [ ] Need to go through all the Gtk.STOCK_* items and remove. Deprecated in 3.10. Very low priority as won't be problem till GTK 4.0 (hopefully!) [ ] Homogeneous_tabbar removed? Why? [ ] terminal.py:on_vte_size_allocate, check for self.vte.window missing. Consequences? [ ] terminal.py:understand diff in args between old fork and new spawn of bash. Consequences? [ ] VERIFY(9)/FIXME(6) FOR GTK3 items to be dealt with [ ] Get the debian build stuff up to date and aligned with the GTK2 where appropriate [ ] LP#1521280 - Reimplement utmp option (for turning off somehow) Now the GTK3 port is done there is also a long overdue port to Python3, especially in light of some distributions trying to eliminate Python2 from the base installs. Yes, Python2 will be with us for a long time yet, but this should serve as a warning. I also have some new items specifically for the GTK3 branch which I'm still thinking about, but I'm not ready to declare. I suspect I might get a bit of unwanted pressure if I were to mention these, so for now they are under NDA. 😃 .. _blog post: http://gnometerminator.blogspot.com/2015/09/so-you-want-to-try-terminator-gtk3.html .. _gtk3 branch: https://code.launchpad.net/~gnome-terminator/terminator/gtk3 -------------------------- Docs for Devs -------------------------- Here is a list of some useful sets of documentation collected together for convenience: +---------------------------+-------------------------------------------------------------------+ | **General** | +---------------------------+-------------------------------------------------------------------+ | Python | https://docs.python.org/release/2.7/index.html | +---------------------------+-------------------------------------------------------------------+ | GNOME Dev. Center | https://developer.gnome.org/ | +---------------------------+-------------------------------------------------------------------+ | Bazaar DVCS | http://doc.bazaar.canonical.com/en/ | +---------------------------+-------------------------------------------------------------------+ | Launchpad Help | https://help.launchpad.net/ | +---------------------------+-------------------------------------------------------------------+ | **GTK 3** | +---------------------------+-------------------------------------------------------------------+ | GObject Introspection | https://wiki.gnome.org/Projects/GObjectIntrospection | +---------------------------+-------------------------------------------------------------------+ | GObject | https://developer.gnome.org/gobject/stable/ | +---------------------------+-------------------------------------------------------------------+ | PyGObject Introspection | https://wiki.gnome.org/Projects/PyGObject | +---------------------------+-------------------------------------------------------------------+ | PyGObject | https://developer.gnome.org/pygobject/stable/ | +---------------------------+-------------------------------------------------------------------+ | Many PIGO autodocs | http://lazka.github.io/pgi-docs/ | +---------------------------+-------------------------------------------------------------------+ | GDK3 Ref. Manual | https://developer.gnome.org/gdk3/stable/ | +---------------------------+-------------------------------------------------------------------+ | GTK3 Ref. Manual | https://developer.gnome.org/gtk3/stable/index.html | +---------------------------+-------------------------------------------------------------------+ | Python GTK+ 3 Tutorial | http://python-gtk-3-tutorial.readthedocs.org/en/latest/index.html | +---------------------------+-------------------------------------------------------------------+ | VTE for GTK 3 | https://developer.gnome.org/vte/0.38/ | +---------------------------+-------------------------------------------------------------------+