docs: ADR 007 - GitHub project organization and issue management #1954
Conversation
ifsimicoded
requested review from
AliceR,
Khanalpooja,
aboydnw,
dzole0311,
fannycc,
faustoperez,
paridhi-parajuli,
sandesh-sp,
sanzog03,
slesaad and
vgeorge
✅ Deploy Preview for veda-ui ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
aboydnw
left a comment
aboydnw
left a comment
There was a problem hiding this comment.
Overall a good start. My two larger points of feedback would be:
- Also formalize this into issue templates across the repos we work in
- To whatever extent possible, use project fields as opposed to issue fields. We work across many repos and sometimes even different orgs (GHG Center as an example of a different org) so using project fields gives us more flexibility and control
| - an estimated start date and estimated delivery date | ||
| - scope of work / what we have agreed to do and not to do (TBD - when this shows up in our project workflow, but it must be included) | ||
| <img width="1269" height="471" alt="Screenshot 2025-12-11 at 12 22 02 PM" src="https://github.com/user-attachments/assets/2accce9b-d2da-4b35-87f4-9bfc1872ba56" /> | ||
| - all related milestones (if relevant) where milestone fields have |
There was a problem hiding this comment.
Milestones in github are specific to repos, so we haven't used them in a while, really ever since VEDA Dashboard expanded beyond just veda-ui and veda-config.
I would suggest using PI objectives for this purpose.
There was a problem hiding this comment.
That makes sense. Related, could you upvote this issue to get milestones added as a cross repo feature, https://github.com/orgs/community/discussions/6296.
It would be nice to have repo features available to projects so both project and repo views have functionality.
| ## Proposed Guidelines | ||
|
|
||
| ### Epics | ||
| (or maybe PI Objectives, I'm not yet sure @aboydnw how you prefer to organize bodies of work*, but I don't think these bodies of work should be tied to PIs as they can often span more than one PI). |
There was a problem hiding this comment.
I've been sort of using both, and not happy with that. Lately, I've been using PI Objectives more because these are actually tracked and used outside of our team. So, gives me some reuse of effort and makes it more likely that things will be updated.
I agree with the issue of initiatives spanning more than one PI. So far I've just been linking tickets by mentioning the previous PI Objective in the description of the new one. It's not a great solution. Open to suggestions there.
There was a problem hiding this comment.
Can you say more about ...
PI Objectives ... actually tracked and used outside of our team
What is specifically is looked at outside of our team? Is it high level -- like these are the projects** slated to be worked on (but maybe not completed) during a PI? Or more macro -- these are specific tickets worked on in a PI?
What are the data points of interest?
There was a problem hiding this comment.
The only tangible, explicit thing that is tracked is PI objectives. If it's not in a PI objective then we don't have good mechanisms for tracking. So some of the smaller stakeholder requests just get tracked on the fly or in tickets. So any large development we try to have represented in a PI objective.
There was a problem hiding this comment.
Updated to remove milestones (only a repo level feature) and use PI objectives as issues.
|
|
||
| All bodies of work should have a parent epic captured in a GH Issue that will be a **living** document for the project for folks to reference both during and after the project work is completed. It should act as the central hub for documentation for the epic that can be referenced in the final epic repo(s) README. | ||
|
|
||
| The epic/objective issue should have |
There was a problem hiding this comment.
I would look at the PI Objective template in /veda-architecture. That's been my template for PI Objectives so far. We can update that to include more fields that are useful for the team.
There was a problem hiding this comment.
Unrelated, should this ADR live in veda-architecture? I'm not sure I understand what goes where -- seems like veda-ui becomes the catch all for things veda, but maybe I misinterpreted, and it should only be focused on library specific items!
There was a problem hiding this comment.
I'd say veda-ui is the catch all for things VEDA Dashboard, but veda-architecture is the catch all for things VEDA. For example that's where we used to put all our PI objectives, although now most of them end up in the relevant repos.
There was a problem hiding this comment.
makes sense, when approved, I'll move this to the wiki, and out of the veda-ui repo
| - all related milestones (if relevant) where milestone fields have | ||
| - title | ||
| - description / scope of work | ||
| - due date |
There was a problem hiding this comment.
due date is important and I haven't found a great solution for it. I've leaned on PI Objectives in the past, a canvas in Slack, and sprint planning tickets.
- Add reference to PR #1954 and new ADR approach - Include quick reference to PR #1927 discussion - Document evolution from label-driven to project board-driven approach - Add @ifsimicoded as co-author
ifsimicoded
force-pushed
the
adr/sd/github_issue_management
branch
from
2547072 to
02b8e2f
Compare
vgeorge
left a comment
vgeorge
left a comment
There was a problem hiding this comment.
@ifsimicoded thanks for writing this ADR, it captures the workflow well. I’d rely more on @aboydnw here, given his deep understanding of the Dashboard ecosystem. Nothing to add beyond update the filename and the title to make this ADR 007.
ifsimicoded
force-pushed
the
adr/sd/github_issue_management
branch
from
6a92727 to
ce5efcc
Compare
ifsimicoded
changed the title
ifsimicoded
changed the title
Updated! That said, when you approve, I'll move this to the veda-architecture wiki, per our earlier conversation since this isn't related to veda-ui code |
vgeorge
left a comment
vgeorge
left a comment
There was a problem hiding this comment.
@ifsimicoded I did another review today and made some suggested edits to include more details around how to handle bugs, issue templates and PRs. Feel free to incorporate and adapt it as you see fit.
| An issue template will be provided to assist in PI Objective issue creation. | ||
|
|
||
| ### Sub Issues | ||
| Tasks will be used to breakdown the work needed to complete an initiative. As timelines become more clear, these sub-issues can be moved under the appropriate Initiative's sub PI Objective ticket. Because these will be defined as issues under an initiative issue or a PI Objective issue, the heirarchy/relationship to the initiative or PI Objective will already be present. We should limit sub-issues to two levels beyond this for task visibility. |
There was a problem hiding this comment.
| Tasks will be used to breakdown the work needed to complete an initiative. As timelines become more clear, these sub-issues can be moved under the appropriate Initiative's sub PI Objective ticket. Because these will be defined as issues under an initiative issue or a PI Objective issue, the heirarchy/relationship to the initiative or PI Objective will already be present. We should limit sub-issues to two levels beyond this for task visibility. | |
| Tasks will be used to breakdown the work needed to complete an initiative. As timelines become more clear, these sub-issues can be moved under the appropriate Initiative's sub PI Objective ticket. Because these will be defined as issues under an initiative issue or a PI Objective issue, the hierarchy/relationship to the initiative or PI Objective will already be present. We should limit sub-issues to two levels beyond this for task visibility. |
fix typo
| - an assigned project(s) of [IMPACT Project Board](https://github.com/orgs/NASA-IMPACT/projects/39/views/8) | ||
| - a project name of VEDA | ||
| - a program increment that corresponds to the PI | ||
| <img width="299" height="244" alt="github issue project settings" src="https://github.com/user-attachments/assets/cdb6421f-173d-4f02-ac58-d90fd314d3c8" /> |
There was a problem hiding this comment.
This link is broken. What this image added here intentionally?
| - continue to use labels for 'good first issue' | ||
|
|
||
| All issues (initiatives, Tech Debt, PI Objectives, sub-issues, bugs) should live in their relevant corresponding repo where possible. Otherwise our current practice is to manage issues in the `veda-ui` repo. | ||
|
|
There was a problem hiding this comment.
| ### Bug Tickets | |
| Bug tickets are operational issues that require immediate attention and are exempt from the hierarchical structure. | |
| Bug tickets should: | |
| - Not have a parent issue (unless the bug is directly tied to an Initiative implementation) | |
| - Live in the repo where the bug occurs | |
| - Use the existing bug template, including context, priority (P1/P2/P3), and reproduction steps | |
| - Include an acronym prefix when Initiative-specific (e.g. `[EIE] Bug: Map not loading in Safari`) | |
| - Link to relevant PI Objectives in the comments for visibility | |
| Bug categorization: | |
| - Initiative bugs: scoped to a specific Initiative implementation | |
| - Infrastructure bugs: affect multiple repos or shared infrastructure | |
| - Production bugs: live site issues requiring immediate fixes |
| ### Pull Requests | ||
| - Should be linked to an issue. You can use [GH keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) like 'closes' or the `#` to bring up issue numbers to link without automations. | ||
| - TBD agreement on PR requirements and turnaround time |
There was a problem hiding this comment.
| ### Pull Requests | |
| - Should be linked to an issue. You can use [GH keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) like 'closes' or the `#` to bring up issue numbers to link without automations. | |
| - TBD agreement on PR requirements and turnaround time | |
| ### Pull Requests | |
| - Should be linked to an issue. You can use [GH keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) like 'closes' or the `#` to bring up issue numbers to link without automations. | |
| - PR title should follow [conventional commit](https://www.conventionalcommits.org) and include Initiative acronym for traceability (e.g., "fix: [EIE] Add globe component") | |
| - Required reviews: at least 1 technical reviewer | |
| - Turnaround time: Review requests are expected to be addressed within 2 business days, unless other time is specific by the team maintaining the repository |
| - continue to use labels for 'good first issue' | ||
|
|
||
| All issues (initiatives, Tech Debt, PI Objectives, sub-issues, bugs) should live in their relevant corresponding repo where possible. Otherwise our current practice is to manage issues in the `veda-ui` repo. | ||
|
|
There was a problem hiding this comment.
| Issue templates will be created and maintained across repositories to standardize: | |
| - Initiative issue creation | |
| - PI Objective issue creation | |
| - Standard task/sub-issue formatting |
Description of Changes
This PR introduces an ADR (RFC - Request For Comment at this stage) for a system to manage our Github issues and project across our shared repos. Please leave your suggestions and comments in the PR so I can make adjustments to the suggested system such that it works for as many folks as possible. Many of our more recent tickets follow this system already 🥳!
It's important that we all agree to using this system so our work can be tracked effectively and easily by not only those that are deeply involved, but those that may come in and out of a project or want to see progress at a higher level.
Once we've agreed on a system, if helpful, I can attach a short video / screenshots on how we can get the most out of github's project and issue features / views.