docs: ADR 007 - GitHub project organization and issue management#1954
docs: ADR 007 - GitHub project organization and issue management#1954ifsimicoded wants to merge 13 commits intomainfrom
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 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.
| Issue templates will be created and maintained across repositories to standardize: | |
| - Initiative issue creation | |
| - PI Objective issue creation | |
| - Standard task/sub-issue formatting |
There was a problem hiding this comment.
@vgeorge
I'm reticent to add this to all repos -- there are too many. Maybe you can help me create templates to add to veda-architecture where it can be copied from.
|
After looking through the doc I am comfortable with approving once the comments from @vgeorge have been addressed. Thanks Simi, this is awesome! |
Co-authored-by: Vitor George <vitor.george@gmail.com>
Co-authored-by: Vitor George <vitor.george@gmail.com>
Co-authored-by: Vitor George <vitor.george@gmail.com>
|
@vgeorge @snmln sorry to let this sit so long. I definitely have a clearer idea on what's helpful for ticket structure, especially as a team lead and the upward reporting in DSE and to Brian. 😆 Maybe it worked out to let this sit. I plan to update the text a bit more with what I've learned and new DSE milestone reporting reqs and move this into veda-architecture docs or if we have shared Dashboard google drive. Do we have a drive? rather than an ADR related to veda-ui. I think it makes more sense there. |
|
I'm closing this ADR in favor of a broader and more comprehensive project organizational plan suggested here: https://github.com/NASA-IMPACT/dse-tasks/issues/181 |
| (TBD - when this shows up in our project workflow, but it must be defined) | ||
| - deployed urls | ||
| - github repositories | ||
| - a resources sections which includes relevant document links (especially those not on GH) |
There was a problem hiding this comment.
Add slack channel
4 participants
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.