[projects beta] Handling features within a project (epics/umbrellas)

[Danielku15]

I just started using the new projects beta and try to get my things organized in a way I am familiar with. Not sure if I am using it the right way but I will try to share some insights into my work style and hope it helps understanding the things which I am struggling with 😁:

In my environment each project is a release cycle. So I create one project for each release I plan (e.g. MyProject 1.3). Now with the project created the project planning starts: I need to think of the features I want to deliver within this release cycle. I do this by adding draft items to the project. Then I convert the features into issues in the repos and describe them. There I create then the feature breakdown using task lists and let GH create another sub-issue for each task. In each sub-issue I then describe again what is addressed there and maybe I already add sub-tasks what I have to take care of there. An example:

In MyProject 1.3 I add native Android support in my cross platform library. As a first sub-issue I extend my toolchain to build a native Android library. The second sub-issue is about adding a proper android control for usage in projects. And the third sub-issue is about creating a deploy chain to package managers like maven for others to consume. Each sub-issue has again subtasks like extending the codebase, tests, documentation,.. that have to be covered.

This project style is coming more from the scrum work style with a epic > stories > subtask structure where epics are usually larger features, stories are the broken down parts which fit into sprints and subtasks is the split of the work within the team (implementation, documentation, testing,..). Thinking of other (scrum) issue tracking systems I got in tough with, this structure was always somehow possible (CA Agile, Jira) and it seems especially large repositories on GH practice similar work styles where large scale features need to be broken down with a clean planning phase of a new project release cycle.

Problem 1: Issue structure

GitHub does not directly have the concept of nested issues where a parent can be considered an epic/feature. You can try to do it by creating issues where you link the other issues with task lists. This is nicely described here: https://docs.github.com/en/issues/tracking-your-work-with-issues/about-task-lists But this does not integrate well with the new projects beta yet. 😞

With the workflow described above you end up with following problems:

1. The sub-issues are not added of the project by default. You have to add them manually to the project in which the parent issue is already.
2. The project does not indicate any hierarchy of features > tasks and their progress like it would be the case with a milestone. This progress can only be seen when opening the parent issue where you see a progress indicator on top.
3. The project board does not allow grouping the issues by their feature > task hierarchy. You just see a flat list of all issues.
4. Creating automations based on this structure is not easy because there is not a 100% clear semantic about parent > children relationships which is understood by the workflows.

Workarounds

1. You can try to workaround this a bit by naming conventions and manual sorting to make it look like a nested hierarchy but it is not really intuitive this way.
2. You can use milestones as features instead of umbrella/parent issues. You see the tracking on milestone level and also the board allows grouping by milestone. But it does not seem to be the intended way of milestones, because you can not track "real" project milestones like a 1.3 feature complete anymore.

Problem 2: Board persistence

You cannot define a board to have a default layout for everyone who opens it. I would like to create boards with defined filters and grouping rules that cannot be changed (only extended?). With this feature mentality I would like to have boards like the following in my project:

1. Release status
   Here you see only "feature" issues (aka. umbrella issues or epic issues) and their accumulated status. You see the X/Y subtasks progress the general status. It is like a high level release progress view what is still to be done until the release/end-of-project without going into the details what each feature still needs.

2. Feature status
   In this view you see the "Feature > Sub-Issue" levels in a grouping mode. For each feature you can inspect what sub-issues/parts are required to complete the feature. It allows more detailed tracking on where each feature stands.

Workarounds

1. As mentioned above, maybe with milestones you can get the desired grouping.
2. You can keep "draft items" as groups and just sort the items into the sections.

Solution proposals

While I am not sure if my work style fits the one of others too, I see the need for the following topics somehow addressed in the new projects system somehow:

1. It would be good to make the parent > children relationship (the one with task lists) a first class citizen in the new projects beta to really allow a feature level view to the project you're working on. It should be clearly documented and described how you can achieve a feature > feature-part > sub-task structure within the issues and projects can be organized. Maybe even deeper structures are required by some people.
2. This nesting also needs to be supported in the workflows. e.g. a feature gets put into progress if any child issue is put into progress. A issue gets put into progress when you create a PR referencing it. Otherwise you end up setting all status values manually while you want to focus on executing your planned project work.
3. It should be possible to define a base filtering/sorting/grouping for each board which is persisted and applied to everyone. Users might add additional filtering or sorting on top to filter the base view.
4. There is a need for a column in boards that indicate the progress of this issue respecting the subtasks (e.g. a progress bar showing X/Y tasks completed).
5. Overall it would be great to have some reference examples by GitHub on how all these task tracking systems can be used on different levels. We have issues, nested issues through task lists, milestones, old style projects, new style projects, releases. It would help people to have some references that really work well together with the GH systems. Even though GH tries to stay flexible, I bet there are some ideas behind the different features and how they should play together. But this is hard to grasp.

I hope this gives some insights on what the new projects beta is lacking for me and how I plan to use it. I found various individual requests to add indention, nesting, grouping etc. but for me they were lacking a bit on the background why it is needed and how they plan to use projects so I thought sharing deeper insights. I also hope that maybe others can share some insights on how they are solving this issue of feature-issues/umbrella-issues/epics and they would like to have it reflected in the new project system of GH.

[mlangenberg]

I'm with you on the same page. GitHub marketing did a great job and got me really excited to use it to track progress during our development cycles, but I feel that the end result is underwhelming.

Weirdly enough, it's even included in their pitch:

Break issues into actionable tasks
Tackle complex issues with task lists and track their status with new progress indicators. Convert tasks into their own issues and navigate your work hierarchy.

So you open a new project board, create several issues with task lists and mark some of them as done. Now I would expect the project board to be updated and reflect the progress on the tracked issues. But it doesn't.

I have to open each issue individually. And when a complex feature isn't tracked with a task list in an issue, but with a dedicated project I can't seem to link to this as a subproject — should I be using milestones instead?

[brammitch]

And when a complex feature isn't tracked with a task list in an issue, but with a dedicated project I can't seem to link to this as a subproject

We're looking at migrating to GitHub Projects and I'm surprised that there's no way to accomplish this.

Complex features across multiple repositories can't be properly tracked in single issue task list. Being able to create a backlog project where an entry could be a feature (child) project, instead of just an issue, would be ideal.

[jfritz]

Adding my two cents here. For me, using Milestones as "projects" or "epics" isn't a tenable solution as the list of milestones is unique per repository, and for our use cases, we have multiple repositories' worth of changes for each epic.

Github has really taken the "Power Developer" approach here rather than the "Power User" approach (Keeping in mind all 3 roles -- applicable to developer, product owner, and scrum master roles, not just developer) to their project board offering here. GitHub Issues and GitHub repositories are 1st and 2nd class citizens respectively because they are what developers work with the most.

This results in less of a focus on product owner use cases -- product backlog management features - I can't even clone a GitHub issue without using the API, let alone link GitHub issues to each other to track issue completion rolled up into an epic.

I've helped Scrum teams in many different industries identify Agile tools that work for them. The tools I have seen have real success with product backlog management features are the tools that treat individually backlog items as a universal, internally linkable object (that could be a user story, bug, theme, enhancement, epic, issue, you name it -- the major differentiating factor being an 'issue type' on the atomic backlog item). This allows universal linking between items and parent/child nesting.

[dlxclem]

@jfritz a simple github action to sync your milestones across your repos does the trick. We're adding our milestones into our main repo, and using that to copy them to our other repos. Since the milestones have the same names, within your github project you can filter by that 1 milestone and it tracks all issues across all repos.

For backlog management, you can nest all your backlog user stories within a status or/and a milestone (since it's easy to move them out of it then, once you're ready to take care of those issues)

[rileybroughten]

Hello! 👋 Tasklists add support for issue hierarchy at GitHub and are currently in Private Beta! You can request access and join the waitlist here.

For more information on how these work, check out the documentation.

[jarpoole]

@rileybroughten @ankneis any update you guys could share given we are at the end of June?

[jacobeatsspam]

I see that the feature was marked as beta for Q2, but I'm not seeing it as an offered feature. Is there any hope this will land soon? 🙏

Edit: I also notice that there is no official documentation on github's support for organization projects

[Aarbel]

@rileybroughten do you have any news about it ?

[Dmi3D]

@rileybroughten Also waiting for this. Really hoping to not have to go back to ZenHub

[GunnarMorrigan]

How do I know if I am allowed to join the open beta?
I joined the list but dont know where to look for 'progres'

@rileybroughten

[rileybroughten]

The private beta is now open for sub-issues, see this discussion for more details!

[rileybroughten]

👋 Check out the changelog announcement where you can sign up to gain access to sub-issues, issue types, and advanced search ✨