Update websites and contributors documentation

[Moini]

I wasn't able to find a link to a current code repo from the website at http://gtgnome.net/ (installed from my distro's repo, and was looking for current developments, as a plugin (export) can't be activated). The repo at launchpad looked abandoned, just like the website did.

Could you please add a link to the current repo at a prominent place on the website (or, if for some reason, nobody has access to the site since 2013, into the Gnome Wiki, which was the second place google found)?

(and thanks for the program :D)

[nekohayo]

Hi there, I'm taking over project maintainership with a new team.

I was told that the "gtgnome.net" domain was actually not under the previous team's control, but was fan-made. I'm not sure it's worth trying to recover vs just making https://wiki.gnome.org/Apps/GTG the official page from here on, and updating all the documentation, though if someone wants to work on a new top-notch website that would do something that we couldn't with a wiki, I wouldn't be against it ;)

[diegogangl]

A simple website using Github pages and Jekyll/Zola could work too. Gnome's wiki isn't very appealing to new/potential users

[ploum]

Changing milestone as having a website is not critical to release 0.4

[ploum]

(of course, any contribution is welcome but it should not be a focus as long as we don't prove to ourselves that we are able to release)

[nekohayo]

In my view, having ordered and up-to-date (as much as possible) contributors documentation (not user manuals, not API reference) reflecting a "well-organized" and actionable project state is probably the most important thing I can do to attract new contributors to accelerate the revival of the project, along with advocacy (i.e. announcements/blogging) and project management guidance (no-nonsense lean/agile-oriented bug triaging).

So I've spent some hours analyzing what is the state of the websites and documentation looks like, and what would probably need to be done to clean up that mess.

Below is my proposed list of changes. Let me know your thoughts on this (if any) or if I should "JFDI" and go through the tasks as fast as possible (maybe I can find other people in GNOME to help me with that). I hope that with this and the reduced list of issues to tackle, the project will be less intimidating for newcomers to contribute to, so I would announce the call for new contributors to join the effort.

---

Global audit and hierarchical list of pages

"GTG" GNOME wiki page (https://wiki.gnome.org/Apps/GTG)

• Remove the link to "GTG's webpage" (which has been dead for years)

  • Point to github instead and consider that the wiki is the official "website" for now

• Enlarge the logo and put a screenshot or two (and bam, you've got a website!)

• https://wiki.gnome.org/Apps/GTG/documentation : review this and merge anything relevant and missing into the offline user documentation, and link to that instead

• https://wiki.gnome.org/Apps/GTG/FAQ : either merge other FAQs items here, or merge this into the user manual

• Simplify https://wiki.gnome.org/Apps/GTG/install to be ONLY about stable pre-built packages installation, link back to the README for dev version installation instructions

  • Integrate Jane's notes on Network Manager dependency from Developer install - ImportError: cannot import name NetworkManager, introspection typelib not found #175 ? Actually with 0.4 we're using Gio.NetworkMonitor now, so probably no dependency needed at all?
  • Integrate notes on dependencies for the "Export and print" plugin from Decommission/deactivate broken plugins and backends, merge critical features into core #222 (comment)

• https://wiki.gnome.org/Apps/GTG/blueprints : this needs some hardcore cleanup... some good detailed ideas in there, but also lots of "normal" feature requests, or catch-all messy non-actionable "try to do everything" wishlists that can't possibly be reasonable with our limited resources... for everything below that doesn't excite me, should I just delete them or "move" them to an "old outdated pages that nobody will care about unless you come forward with a patch for it"?

  • Fix the broken hyperlinks
  • Clean/merge/delete the blueprints subpages below
  • https://wiki.gnome.org/Apps/GTG/blueprints/backends : ancient (2011) and not actionable. Delete?
  • https://wiki.gnome.org/Apps/GTG/blueprints/repeated_tasks has some interesting brainstorming content... keep?
  • https://wiki.gnome.org/Apps/GTG/blueprints/QuickAddSyntax not sure this makes sense. Lots of complicated parsing/engineering, vs simply asking the user to create a new task before filling it... move to rejected ideas?
  • https://wiki.gnome.org/Apps/GTG/Filtering%20by%20multiple%20tags : delete as this is a duplicate of an issue ticket
  • https://wiki.gnome.org/Apps/GTG/blueprints/taskeditor-rework (2012) : archive this as some historical dev thing, but otherwise not actionable
  • https://wiki.gnome.org/Apps/GTG/blueprints/desktopintegration (2012) : delete.
  • https://wiki.gnome.org/Apps/GTG/blueprints/statistics (2012): maybe keep around as a brainstorm for statistics if we could have someone to implement that feature
  • https://wiki.gnome.org/Apps/GTG/blueprints/brief-ideas (2014): delete.
  • https://wiki.gnome.org/Apps/GTG/blueprints/TomboyNoteSupport (2009): delete.
  • https://wiki.gnome.org/Apps/GTG/blueprints/HamsterIntegration (2009): delete.
  • https://wiki.gnome.org/Apps/GTG/blueprints/GTGApplet (2009): delete.
  • https://wiki.gnome.org/Apps/GTG/blueprints/removingmultipletags (2012): delete
  • https://wiki.gnome.org/Apps/GTG/blueprints/ArborescenceInWorkviewTitles (2012): archive? Only interesting as a historical context for the notion of projects with https://lists.launchpad.net/gtg-contributors/msg00769.html ?

• https://wiki.gnome.org/Apps/GTG/feature_requests : archive this to something like "2011 feature requests summary", and replace by a page explaining that we will accept NO feature requests without a promise to contribute and maintain a patch for it?

• https://wiki.gnome.org/Apps/GTG/Roadmap

  • Fix the broken hyperlinks
  • Update/rewrite the roadmap for 0.4, 0.5, and "beyond"
    • Should we just throw out the notion of hardcoded roadmap and say that we rely purely on whatever is targetted at a milestone? And link to the various ticket tags to entice contributions (i.e. an agile/dynamic roadmap of sorts)
  • https://wiki.gnome.org/Apps/GTG/Design has interesting contents/brainstorming/research, but probably not the right time to be studying them now, we need to get a release out of the door. Note: it is also linked from the front page. Maybe add a proper explanation of the status of this thing?
  • The rest of the links in that page are duplicated on the blueprints page!!

• https://wiki.gnome.org/Apps/GTG/release_names has nice historical info and is not complicated, let's keep it for fun

  • Update the statistics upon 0.4 release (will need special accounting of the "days of devel")
  • Add a short explanation of new codenames and version numbering scheme (0.4, 0.5, 0.6, etc.: screw stable/unstable, screw minor numbers, etc.)
  • Using the WayBack Machine at https://archive.org, provide archived/fixed version of the previously linked announcements

• Rewrite https://wiki.gnome.org/Apps/GTG/contributing

  • This is from the 2009 and 2012 era. The page needs a major rewrite, unless there is some other page or tutorial we can link to?
  • This references Bazaar, and while I used to love Bazaar, I have, like the rest of the world, moved on to Git.
  • Pointing to LaunchPad = no. (unless we somehow want to move away from things like GitHub/GitLab)
  • The testing/debugging techniques listed there might still work and be valuable? Someone should confirm this.

• Rewrite https://wiki.gnome.org/Apps/GTG/bugstriaging

  • Explain our lean/agile "be able say 'no unless you provide a patch'" approach for 2020+; see https://fortintam.com/blog/reducing-our-core-apps-software-inventory/
  • Explain that we have abandoned LaunchPad, and that nobody in the maintainers team will look at bugs in distro trackers either; distro bug trackers are where bug reports go to die.
  • Explain that bug reports tested to occur with the git version (with the "reproducible-in-git" tag) have a higher chance of being considered
  • Explain that our flatpak packages (or manual git checkout) are the only officially accepted testing/QA/bug reporting platform
  • Rework the bug status descriptions to match them with https://github.com/getting-things-gnome/gtg/issues/labels

• Rewrite and simplify https://wiki.gnome.org/Apps/GTG/becoming%20a%20gtg%20developer

  • Take out LaunchPad
  • Explain the distinction between the maintainers (infrastructure admins) team vs contributors team (direct commit access etc.) vs occasional/drive-by contributors (anyone else who knows how to use git and/or this wiki, or is good at testing and investigation)
  • Document the Tox testing support (Add tox support #239) somewhere (here, or the Git repo's readmes/docs?)
  • Simplify procedures to remove impediments

• Cleanup the "Plugins" stuff

  • Migrate and delete https://wiki.gnome.org/Apps/GTG/pluginHowTo
  • Delete https://wiki.gnome.org/Apps/GTG/external_plugins
  • Do something (update/delete/rewrite?) with https://wiki.gnome.org/Apps/GTG/plugins ?
    • Instead of maintaining a static list of plugins, maybe just point to the relevant git code directory and explain that some are broken/in need of new maintainers?
    • Document the broken/deactivated/deprecated plugins from Decommission/deactivate broken plugins and backends, merge critical features into core #222 and make a clear call for contributions, including a mention that this is the reason why the "Synchronize" menu item is disabled.

• Properly indent/organize the "For new contributors" section

  • https://wiki.gnome.org/Apps/GTG/dbus is probably good/relevant to keep around, though I have no idea if it still works
  • Move https://wiki.gnome.org/Apps/GTG/UserStories
    • It is not dev documentation, I suspect it should become a subpage of the "Design" page
  • Delete https://wiki.gnome.org/Apps/GTG/Backends ; it is devoid of useful information, and the links are broken.
  • https://wiki.gnome.org/Apps/GTG/DataModel : I don't know if this is still up-to-date, is it still like this or was this redone entirely in 0.3.1/0.4? Diego says "don,t convert that, it'll change" so keep it in the wiki, archived under the historical section for old maintainers.

• Explain the existence (and encourage the use) of "gtg.sh" which runs in debug mode and lets you test with fake data instead of your real data

  • document that the data is in the "tmp/default/xdg/" subdirectory of the git checkout when running with gtg.sh, also that you need to hack the paths in projects.xml in you want to reuse existing data copied into that directory.

• https://wiki.gnome.org/Apps/GTG/development needs to be renamed, it's a page about performance profiling (and is worth its weight in gold)

• https://wiki.gnome.org/Apps/GTG/ReleaseProcess needs to be updated:

  • Remove LaunchPad references (what do we do about translations, just abandon that tooling and expect that motivated-enough individuals will throw updated files at us through github?)
  • There would need to be a Flatpak documentation page (or link to something 3rd-party) to replace the "Debian package" section in the release process

• Delete https://wiki.gnome.org/Apps/GTG/code_swarm

  • This is not mission-critical, depends on a script from 2009 hosted at Google Code (so it's only a matter of time before it disappears), and I suspect you can just do that with "gource" instead?

• Delete "GTG checks" pointing to http://mumak.net:8080/job/GTG/ (dead link) or replace with something pointing to whatever current CI status page

• Move the "Google Summer of Code" section to a subpage

• https://wiki.gnome.org/Projects/liblarch

  • Probably all mostly still all relevant. Lots of sublinks.
  • Out of scope for me to look at, I'll just assume this should be kept as-is.
  • Merge in Ploum's explanation from Merge liblarch into gtg #286 (comment)

GitHub main project/code repository

• https://github.com/getting-things-gnome/gtg (source here) has general installing and developer documentation
  • Simplify and split contents
    • Should the info on dependencies, plugins, etc. be split off to a separate readme file or wiki page (or linked from the wiki page)?
  • Update the bunch of "Want to know more?" URLs at the end (only keep the link to the wiki page, the rest is all dead)
• https://github.com/getting-things-gnome/gtg/tree/master/docs/source/man has basic user documentation manpages; they seem to be still up-to-date? Probably nothing to do there.
• https://github.com/getting-things-gnome/gtg/tree/master/docs/userdoc/C is the main user documentation. We need to outsource this, we shouldn't waste coders' limited time with what can be done by enthusiastic users.
  • Announce a recruitment initiative for a new team of non-coding contributors who would be motivated in updating the whole user manual
• https://github.com/getting-things-gnome/gtg/blob/master/CHANGELOG
  • Clarify what is a LaunchPad issue, what is a GitHub issue, etc.?
  • Rename 0.3.2 to 0.4, and prefix the existing list with simply a link to the relevant milestone? Or do we need to still output a copy-pasta of the list of github issues fixed for distro "ChangeLog" packaging purposes?
• https://github.com/getting-things-gnome/gtg/blob/master/AUTHORS needs to be updated
  • Reverse the chronological order of releases in the AUTHORS file (this will make recent contributors more prominent), and add new contributors (like Diego!) to the 0.4 release in AUTHORS
  • Split "The GTG Team" into "Previous maintainers" and "Current project admins" and link to https://github.com/orgs/getting-things-gnome/teams
  • Use the PTV technique: provide git shortlog, git blame commands, and link to openhub's + github's + gitlab's contributors analytics, instead of a spammable static list of people...
• https://github.com/getting-things-gnome/gtg/blob/master/HACKING : I wonder if it would be better to move the contents to a wiki page (with proper formatting, subpages, etc.), and simply link to it from the HACKING file?
• Document why https://github.com/getting-things-gnome/gtg/blob/master/requirements.txt exists
  • It is used by PIP to solve dependencies. To be explained in the README.

ReadTheDocs (https://gtg.readthedocs.io)

• Seems to be just an export from the .rst files from our repository. What's the procedure to update this?
• Why would we actually care to have this on "yet another" third-party website, vs just keeping it in github? I would say we need to find who maintained the account there, and delete that account.

Dedicated website

• Not in my plans, personally speaking. The GNOME wiki can probably do 80% of the job, and will be zero infrastructure to maintain.
• If someone wants to do something amazing for this down the road, this could be considered

LaunchPad

• I would say we kill this with fire (see issue After the move to GitLab, figure out how to batch-close tickets on LaunchPad #385). Filled to the brim with old stuff, overflowing with bug reports and blueprints and whatnot, it will only be demoralizing and action-paralyzing to look at it.
• Should we keep the mailing list or nobody cares about that and we should only manage everything through the bug tracker? If we want to have some users community around, shouldn't this be a Discourse forum instead (which can receive announcements and serve as a place where ponies-on-rainbows feature discussions can be held until someone is willing to provide a patch? Or will this, again, duplicate the github issues tracker?)

[diegogangl]

https://wiki.gnome.org/Apps/GTG/blueprints/repeated_tasks has some interesting brainstorming content... keep?
https://wiki.gnome.org/Apps/GTG/blueprints/QuickAddSyntax not sure this makes sense. Lots of complicated parsing/engineering, vs simply asking the user to create a new task before filling it... move to rejected ideas?

I'd make a ticket for repeated tasks so we can talk about it here. I think the first section of that page is the most useful. The only useful thing about the quick syntax one is adding tags directly. You can sort of do this now, but it needs polishing.

Should we just throw out the notion of hardcoded roadmap and say that we rely purely on whatever is targetted at a milestone? And link to the various ticket tags to entice contributions (i.e. an agile/dynamic roadmap of sorts)

Release early, release often. I think it'd be better to set some targets at the begging of a release cycle (like a MVP) and tag them with a milestone.

Simplify and split contents
Should the info on dependencies, plugins, etc. be split off to a separate readme file or wiki page (or linked from the wiki page)?

We need to remove dependencies for plugins once we clean them up

https://github.com/getting-things-gnome/gtg/blob/master/requirements.txt : I suppose this is needed for CI or something, maybe we should document the existence of that file from one of the wiki/readme pages about dependencies?

requirements.txt is used to install requirements via pip.

Reverse the chronological order of releases in the AUTHORS file (this will make recent contributors more prominent), and add new contributors (like Diego!) to the 0.4 release in AUTHORS

\o/

Should we keep the mailing list or nobody cares about that and we should only manage everything through the bug tracker? If we want to have some users community around, shouldn't this be a Discourse forum instead (which can receive announcements and serve as a place where ponies-on-rainbows feature discussions can be held until someone is willing to provide a patch? Or will this, again, duplicate the github issues tracker?)

Yeah, launchpad needs to die. I didn't know we had a mailing list. As for a user forum, maybe we should wait and see if we need something more than the tracker. For more direct conversation, we could have a matrix chatroom (on riot.im).

[nekohayo]

This is now 99% done, including fixing all the links in https://wiki.gnome.org/Apps/GTG/release_names so that we can see the old release announcements even if the website was destroyed in a fire.

[trst]

Dedicated website

• Not in my plans, personally speaking. The GNOME wiki can probably do 80% of the job, and will be zero infrastructure to maintain.
• If someone wants to do something amazing for this down the road, this could be considered

100% agree with the initial statement, but if that's a pathway the team is interested in exploring, I'd love to help tackle it.