Zenhub is an agile project management tool that is closely integrated with GitHub. In fact, it is so integrated that GiHub issues appear as issues on on the Zenhub project boards and vice versa. We (the JEDI team) are now using ZenHub to manage code development (including sprints), track issues, and promote collaboration.
Creating a ZenHub Account
To get started, please go to:
and select Get started in the upper right-hand corner. Then just follow the menu-directed instructions. There is no need to create a new username or password - you can just log in via your GitHub account. As you go through this setup you will be given the option to install a browser extension. Please do so. This will allow you to access the project boards and progress reports directly from the github repos.
The browser extension only works for Google Chrome and Firefox. If you go through the startup and it's still not installed, you can install it manually here:
https://www.zenhub.com/extension
If use a different browser, you may have to log in directly to https://www.zenhub.com to see the project boards.
Currently (March 28, 2018) we have one code development project board that is linked to four JCSDA repos (fv3, fv3-bundle, fv3-jedi, and fms). We will link in more repos as they are migrated to the JCSDA organization on GItHub. And, we likely add more project boards as we work ZenHub into our JEDI work flow. If you have the browser extension installed, you can access this board by going to any of these four GitHub repos and selecting the ZenHub tab near the top of the page. You should also see a Zenhub icon in the top right of your browser - you can use that to access your Zenhub Dashboard, which includes information about your account.
You will find a few issues already on the board to get us going. Please add more. To add a task, select New Issue in the upper right-hand corner of the board. By default, this issue will be created under whichever repo you accessed the board from. If you want to tie the issue/task to a particular repo, select the green + sign adjacent to the New Issue button. Then scroll down and select the relevant repo.
Important
To see all issues spanning all the repos for the project board, go to the Repos tab on the upper left of the board (right above the New Issues column) and select show all.
ZenHub Terminology and Use
Now, a little Zenhub terminology. The columns are referred to as Piplelines. By default, new issues go into the New Issue pipeline but you can move them to the Backlog pipeline or, if you're working on it now, to the In Progress pipeline. The Icebox pipeline is for low-priority tasks that we don't need to deal with immediately but we should revisit at some point in the future. You can collapse this (or any) column by selecting the collapse pipeline icon just to the right of the column title.
When creating or modifying an issue, you can assign up to 10 people that are responsible for carrying it out, and you can give it a label, such as "enhancement" or "bug fix".
You can also (optionally) assign it a difficulty level with the drop-down Estimate menu. As a rule of thumb, we can think of one story point as a half day of dedicated work. So, if you think something will take two days of dedicated work, assign it 4 story points. That does not necessarily mean that it will be done in two days since we rarely have two full days available to dedicate to a single task but it gives us a feel for how complex the job is. This is an art, not a science - don't worry about being accurate. As we gain more experience with this, we will get better at using this in a meaningful way. It is not too important now, but the idea is that it will become a valuable tool to plan future code sprints - if we know roughly how many story points the team can get through in, say, two weeks, it will help us to define reasonable goals for each sprint.
The Zenhub terminology for sprints is Milestones. In addition to these, you can also organize tasks into broader, longer-term development efforts called Epics. No need to worry about that for now - you can ignore those options when you create new issues. But, as we work together on this, we will likely see Epics and potential Milestones emerge.
We should try this for a while and see how it goes. We have the option to customize the pipleline titles, labels, etc however we wish. We can also define new project boards and epics. So, if you have suggestions on how to customize it, feel free to create a new issue in the Review/QA pipeline and we all can comment on it.
Currently a particular GitHub repo can only be linked to one project board. However, ZenHub is aware that its user community wants the capability to have repos span two or more project boards. They are actively developing a new feature called Workspaces that will enable this and that will hopefully be released soon - for more info see: https://github.com/ZenHubIO/support/issues/139.
Questions?
For more information about ZenHub's components and capabilities, please see the excellent tutorials located here:
Please give ZenHub a try. If you have any questions, please email Mark Miesch at miesch@ucar.edu. Or, if you have a comment or suggestion that you would like the JEDI team as a whole to consider, please feel free to add it to the project board!