Proposal: Project Management Guidelines

[karianna]

As the project has grown and we move to Eclipse, there's been a few discussions on slack recently about having the project look at guidelines for how we organize, manage and communicate. Whilst our philosophy has been to let each team use tooling and processes that suit them (as long as we adhere to the Eclipse rules), it's helpful to explore areas where we can all agree on how to manage things like GH Issues, Projects, and Decision Logs such as Architecture Decision Records (ADRs) used in the API project. The Proposal is as follows:

Discuss before Do Guideline

We strongly encourage folks to discuss changes in the open Slack channel, and/or in the appropriate mailing list, and/or the GH issue before making changes. Any decision should be recorded in the GH issue (which itself can link to an Architecture Decision Record (ADR), design doc, etc if a larger piece of architecture or design needs to be communicated.

When there's a difference of opinion, we encourage longer discussions until consensus is reached. In the very rare cases of an impasse, folks can ask the TSC to make a decision to avoid paralysis.

GitHub Projects and Kanban

• For each repository we use a default GitHub Project (of the same name) with the full 'Kanban' template.
• We also have organization-wide projects such as Top Priority and Good First Issues.

Managing Issues

Issues typically live in the default GH project for the repository and can also be added to an organization-wide project if warranted.

• Assignees: We try to only assign folks when they are actively looking at the issue (or are about to).
• Labels: We try to always label GH issues. Labels are repository dependant, but we typically use the minimum set:
  • Bug
  • Enhancement
  • Duplicate
  • Waiting on OP
  • Won't Fix
• Projects: Issues either live in ZenHub or in GitHub project(s) for the repository. If ZenHub is not used, then the GitHub issue can be added to an organization-wide project if warranted. Issues move along in a Kanban workflow and we typically have:
  • TODO - Noone has been assigned or the Assignee has not started yet.
  • In Progress - The Assignee is actively working on it.
  • In Review - PR is being reviewed. FYI - There are a few mini-review states, but they tend to be automated.
  • Done - Issue is resolved.
• Milestones: We use Milestones to indicate when work is going to be looked at (no promises on completing!)
  • <Month | Name> - Indicates that the item has been triaged and schedule in a Month or in a particular sprint, project, etc.
  • Backlog - Indicates the issue has been triaged, is deemed to be something we want to do but has not been scheduled
  • Icebucket - Indicates the issue has been triaged and is deemed something to do in the distant future
  • No Milestone - The issue has not been triaged

Triaging Issues

Teams are responsible for triaging their own issues. It's recommended practice to try to do this 1/week as a full team and ensure that critical issues don't get missed and that the Backlog is groomed. The goal is to keep repositories < 150 open issues, preferably < 100 (these numbers come from research into OSS projects and when it gets to the stage that you can see the forest for the trees).

Pull Requests

Pull Requests should follow the CONTRIBUTING.md guide. It should be the goal of each team to kee the number of open PR's < 10, preferably as close to 0 as possible.

Documentation

Documentation is critical to the project

README.md

This document should clearly state what the repo is for and how to use the artifacts produced by it. Ideally, it should also contain:

• Build Status
• How/When/What/Where the artifacts are deployed to staging and production.

CONTRIBUTING.md

This document should clearly state how to build, test, and what's expected in Pull Requests. Ideally, it should also contain:

• Code conventions, linting rules etc

SECUIRITY.md

This document covers the security policy and how to submit issues.

FAQ.md

Spillover documentation from README.md and CONTRIBUTING.md which fairly common but doesn't need to be front and center. Should be linked to by those two docs.

Wiki

TBD

[sxa]

I would also suggest:

• PRs with at least one review (except in emergency circumstances) are mandatory for merging of all GitHub changes (but allow individual repos/teams may choose to use a higher number if they have enough people to do so!).
• What we can do to encourage people to respond on PRs/issues where they have been "stale" for a while if they are blocked on a response? Should we have a policy around this, particuarly if something is marked as a top priority?
• Should people always self-assign to an issue when working it, or is it valid for a team to assign an issue to an individual if it is known that only one person has the knowledge/understanding to progress it?

Thinking about it (And I appreciate that I said I was in favour of retaining it!) I've personally not found the full board process too useful over and above other assignments other than potentially as an overall view. Working on this project I've found that the assignment to the individual and putting it into a milestone is generally adequate to cover "About to do", "In-progress", "In review" and I'm not sure if we signficantly benefit from going through all those states explicitly. Not against it, but I don't want to be setting multiple things that indicate the same information.

Also this doc mentions "Build status" as a required part of README.md - we should clarify what that means in a cross-repository sense.

[smlambert]

I like the idea of having a common set of guidelines for project management at Adoptium, and its sub-projects. I do not necessarily want to have 1 project per repo. For AQAvit, it will make sense to have 1 project for the 7 test-related repos (either using an organization-wide or zenhub project). I will propose this in this week's AQAvit call to find out from the AQA core-test team their thoughts.

From this week's Adoptium community call, @karianna volunteered to move this to a Google doc, so that others can give opinions and comments.

• Decide to use a common set of guidelines (Yes or No)
• Decide on the details of common guidelines (by comments in the Google doc and/or this issue)

[smlambert]

Consensus from discussions in and after AQAvit call is to setup a Zenhub board for the combined set of AQAvit repos and manage the work across them in a unified manner (reviewing in the regularly scheduled AQAvit meetings), and follow the common Adoptium guidelines for labels/milestones etc.

Also recommend that core team, reviewing and merging PRs, adding labels to issues, etc to regularly attend AQAvit meetings to have an understanding of the work and goals and reduce mistakes & mislabeling.

[karianna]

Consensus from discussions in and after AQAvit call is to setup a Zenhub board for the combined set of AQAvit repos and manage the work across them in a unified manner (reviewing in the regularly scheduled AQAvit meetings), and follow the common Adoptium guidelines for labels/milestones etc.

Also recommend that core team, reviewing and merging PRs, adding labels to issues, etc to regularly attend AQAvit meetings to have an understanding of the work and goals and reduce mistakes & mislabeling.

Not against ZenHub, but is there a cost involved there?

[smlambert]

Zenhub is free for open-source projects and public repositories. The only thing we will need to do is to make a request to the Eclipse infra team to approve Zenhub hook to the AQAvit repos (or any repos we may wish to combine under one Zenhub board). I see that other some Eclipse projects are using Zenhub, so there is precedence.

We are using it for the website-adoptium work currently (in the AdoptOpenJDK github organization), and learning about more of the features through that work.

We could set up an Adoptium organization-wide project for AQAvit, but Zenhub offers some additional features over and above what that org level project does (including but not limited to automation and relationships of workflows across different workspaces, reporting, etc)

[karianna]

Awesome I love the product, let's see if everyone else is happy with it and we can try it in the other adoptium orgs as well

[karianna]

In the Adoptium PMC meeting we agreed to move this one across.

[hendrikebbers]

Since all the MD files are listed in the text a CODE_OF_CONDUCT.md should be mentioned (as far as I know Eclipse provides a default one). Regarding Wiki: From my point of view it would be the best to start with simple GitHub Wiki pages and move everything to the Adoptium.net documentation once it can be used (see https://github.com/adoptium/adoptium/issues/50).

[karianna]

AS an FYI - we've now moved all repos to ZenHub but much triage and Epic sorting work still need to be done.

[sxa]

Once this release is sorted we really need to work on getting consensus on this ... There appears, at least superficially, to be a quite a lot of things that violate the suggestions in here going on. "Documentation is critical to the project" is a mantra that I've been trying to push for as much as possible, and we need to ensure that all new stuff that we add in is documented, but also usable (i.e. if it's overly complex to get started with it, we have to ask ourselves why as this will put off new contributors)