Time for another round of tool talk! I've done a similar thread or two in the past. While contributors are free to pick their own tools I'm still hunting the perfect template we can recommend for project work.
New tool candidate this time around: Zenhub.io - largely in part from our first ever need for structured work with actual project dates, thanks to GSOC!
Going from least amount of needed organization to most (entirely dependent on how much a contributor wants) and also chronologically from design through implementation I present my recommendations:
Just need some brainstorming (what to do)
Tool: General forum suggestion thread or Trello board
Example: @Anthodeus' combat brainstorming thread or our Destination Sol backlog Trello board.
Purpose: Just need somewhere to dump contents of brain or accept community proposals. Would pull more structured stuff out of this later when time to design more closely and implement. Could span many topics that could end up in all kinds of different GitHub repos (like multiple separate modules)
Design time (how to do it)
Tool: Specific forum suggestion thread and/or GitHub issues
Example: A single thread covering a single module in detail or individual GitHub issues describing what needs to be implemented
Purpose: At this point we're writing up actual design notes, which may be needed for complex topics or where the designer isn't necessarily doing the implementation. Could be skipped if you know what you're doing and it is a one-person job.
A work thread like this could later be moved into the Core or Module forum for implementation
Work time (who will do it)
Tool: Specific forum thread covering the feature either as a Core project or a Module and/or GitHub issues. Optionally ZenHub or Waffle.io (look for more notes later)
Example: Module thread for JoshariasSurvival, ZenHub board for JoshariasSurvival
Purpose: At this point work is being implemented by a volunteer, possibly relying some on earlier design resources. Good discussion in the forum or on GitHub issues on implementation details.
Could be pulling new todo items off a Trello board if appropriate.
Getting organized (when to do it)
Tool: GitHub, ZenHub
Example: Scheduling work for a GSOC proposal. See Cervator/Terasology for a simple setup (may change in the future) - be sure you have the ZenHub browser plugin installed before viewing.
Purpose: If able to dedicate a consistent amount of hours to work estimates and target dates may actually work and even help stuff get done! This would be the case for GSOC students or maybe contributors working on unofficial projects.
In this context ZenHub is probably best used in the student's own fork, so issues, labels, milestones, etc can all be changed freely by the student. ZenHub can do multi-repo integration and move issues, but those scenarios are more advanced and likely overkill.
One suggestion would be aiming to do a PR to merge work when an epic or milestone is completed (the epic issue could probably even be moved to the engine repo). Read on for more details!
ZenHub.io
ZenHub is a browser addon for Chrome/Firefox that alters the GitHub website to add a kanban board and other features right in the usual interface. It somewhat compares to Waffle.io which started as an intern experiment by Rally, which already has plenty of tools they sell, so it didn't advance particularly fast. Both support "merging" repos together as far as tracking issues in one place goes. ZenHub at this point seemingly only lacks:
Nice things that ZenHub does offer:
Usage for GSOC
For GSOC I think we should use:
Next step there would be identify individual topics for more detailed design, what is realistic to get done in a first round. Maybe apply MoSCoW on the different major topics to figure out some checklists for what needs to get done first, per feature. This could perhaps involve Trello at a light level, but not card-per-issue since that would be a waste of work to then later replicate in GitHub issues. A Trello card checklist could be used to later make issues one by one, while checking off the items in Trello.
After that it would be time to get to work and in this case determine who does what as several students have expressed interest in that area, including @korp and kartikey.
Finally each contributor could create detailed issues in their personal engine fork, even if the work actually involves one or more modules. Using just the engine fork helps keep everything centralized, yet won't spam the main engine repo.
You could merge student forks with the main engine or individual module repos. Epics can contain issues from other repos in that case. But this gets awkward fast plus it may hit permission issues. Probably will get easier later.
I also would advice against linking commits with issue numbers in forks. When merged to the engine the numbers change but the commits do not. Additionally an issue auto-closing from a commit being pushed to a fork will move that issue in ZenHub to the closed column, when you may merely want it in the "Done" column until it is merged upstream.
For a template for how to organize ZenHub see my personal repo on GitHub (including milestones and burndown charts with the exact GSOC dates). If you want the same labels as the engine repo you can auto-import them with this tool (probably run it as a local website since it uses your password). Edit: Looks like you have to make at least one change to have the "Commit changes" button turn active, such as deleting the deprecated "Contributor Friendly" label.
Phiew, that's a lot of text. I tried to keep it short, honest!
New tool candidate this time around: Zenhub.io - largely in part from our first ever need for structured work with actual project dates, thanks to GSOC!
Going from least amount of needed organization to most (entirely dependent on how much a contributor wants) and also chronologically from design through implementation I present my recommendations:
Just need some brainstorming (what to do)
Tool: General forum suggestion thread or Trello board
Example: @Anthodeus' combat brainstorming thread or our Destination Sol backlog Trello board.
Purpose: Just need somewhere to dump contents of brain or accept community proposals. Would pull more structured stuff out of this later when time to design more closely and implement. Could span many topics that could end up in all kinds of different GitHub repos (like multiple separate modules)
Design time (how to do it)
Tool: Specific forum suggestion thread and/or GitHub issues
Example: A single thread covering a single module in detail or individual GitHub issues describing what needs to be implemented
Purpose: At this point we're writing up actual design notes, which may be needed for complex topics or where the designer isn't necessarily doing the implementation. Could be skipped if you know what you're doing and it is a one-person job.
A work thread like this could later be moved into the Core or Module forum for implementation
Work time (who will do it)
Tool: Specific forum thread covering the feature either as a Core project or a Module and/or GitHub issues. Optionally ZenHub or Waffle.io (look for more notes later)
Example: Module thread for JoshariasSurvival, ZenHub board for JoshariasSurvival
Purpose: At this point work is being implemented by a volunteer, possibly relying some on earlier design resources. Good discussion in the forum or on GitHub issues on implementation details.
Could be pulling new todo items off a Trello board if appropriate.
Getting organized (when to do it)
Tool: GitHub, ZenHub
Example: Scheduling work for a GSOC proposal. See Cervator/Terasology for a simple setup (may change in the future) - be sure you have the ZenHub browser plugin installed before viewing.
Purpose: If able to dedicate a consistent amount of hours to work estimates and target dates may actually work and even help stuff get done! This would be the case for GSOC students or maybe contributors working on unofficial projects.
In this context ZenHub is probably best used in the student's own fork, so issues, labels, milestones, etc can all be changed freely by the student. ZenHub can do multi-repo integration and move issues, but those scenarios are more advanced and likely overkill.
One suggestion would be aiming to do a PR to merge work when an epic or milestone is completed (the epic issue could probably even be moved to the engine repo). Read on for more details!
ZenHub.io
ZenHub is a browser addon for Chrome/Firefox that alters the GitHub website to add a kanban board and other features right in the usual interface. It somewhat compares to Waffle.io which started as an intern experiment by Rally, which already has plenty of tools they sell, so it didn't advance particularly fast. Both support "merging" repos together as far as tracking issues in one place goes. ZenHub at this point seemingly only lacks:
- Ability to include multiple members of one repository's network graph (can't add a second repo with a name that's already included?)
- Ability for grouped repos to overlap with other groups (as in, at present one repo can only be in one group, which is tricky for utility modules used several places)
- For example JoshariasSurvival is working with 20 grouped repos as of this writing. However, no other module grouping can overlap with those 20, unlike with Waffle
- For example JoshariasSurvival is working with 20 grouped repos as of this writing. However, no other module grouping can overlap with those 20, unlike with Waffle
Nice things that ZenHub does offer:
- Epics - groups of issues which may include other epics, allow for dependency relationships between issues
- Burndown chart - based on milestones with a target date (and a start date you set on the burndown chart page for each milestone)
- Story point estimation that are reflected on epics and the kanban board (although a nested epic won't count its issues' story points into upstream calculations)
Usage for GSOC
For GSOC I think we should use:
- One (or more for multi-topic proposals) forum thread(s)
- One central issue (per topic) in the MovingBlocks/Terasology GitHub tracker
- Many issues in milestones in the students personal fork on GitHub, possibly including Epics
- Perhaps specifically three milestones: Bonding period, work period 1, work period 2
- ZenHub in the student's fork to show burndown charts per milestone for estimating progress
Next step there would be identify individual topics for more detailed design, what is realistic to get done in a first round. Maybe apply MoSCoW on the different major topics to figure out some checklists for what needs to get done first, per feature. This could perhaps involve Trello at a light level, but not card-per-issue since that would be a waste of work to then later replicate in GitHub issues. A Trello card checklist could be used to later make issues one by one, while checking off the items in Trello.
After that it would be time to get to work and in this case determine who does what as several students have expressed interest in that area, including @korp and kartikey.
Finally each contributor could create detailed issues in their personal engine fork, even if the work actually involves one or more modules. Using just the engine fork helps keep everything centralized, yet won't spam the main engine repo.
You could merge student forks with the main engine or individual module repos. Epics can contain issues from other repos in that case. But this gets awkward fast plus it may hit permission issues. Probably will get easier later.
I also would advice against linking commits with issue numbers in forks. When merged to the engine the numbers change but the commits do not. Additionally an issue auto-closing from a commit being pushed to a fork will move that issue in ZenHub to the closed column, when you may merely want it in the "Done" column until it is merged upstream.
For a template for how to organize ZenHub see my personal repo on GitHub (including milestones and burndown charts with the exact GSOC dates). If you want the same labels as the engine repo you can auto-import them with this tool (probably run it as a local website since it uses your password). Edit: Looks like you have to make at least one change to have the "Commit changes" button turn active, such as deleting the deprecated "Contributor Friendly" label.
Phiew, that's a lot of text. I tried to keep it short, honest!
Last edited: