# Gluster github movement details

Gluster is moving towards using github more mainstream than before. There are a couple parts to this move,

- Release scope and planning using github projects
- Moving away from bugzilla to github issues for bugs and feature requests

The move towards using github to track release scope started with the 3.10 release, as announced here [[1]](#links). At which point in time we still held onto bugzilla as the source for all bugs and feature requests.

We are now making the bigger change, shedding bugzilla and moving to use github issues for all requests. This mail details the various aspects of the same and feedback is being sought from the community, to help us get there.

## Motivations:
- Primary motivator is to be able to share and discuss longer ranging project goals and plans with the community.
- This is why our release scope is being put up in github projects, with plans detailed beyond the current release
- Further we have a series of focus areas that we as the development community are focusing on, which we believe can be enriched further by the community (see [[1]](#links) for focus areas)
- Further to this, we also would like better community participation and make it easier for our users to report and track issues. This is where moving to github issues and shedding bugzilla comes in. Also, it becomes much easier to track feature requests and bugs in one tool.

## What is not happening in github: (let's get this out of the way!)

### We are not accepting github PRs
We are not moving away from gerrit [[2]](#links), and adopting a github PR model for accepting commits. There are a variety of reasons for this, primarily we like the strength of gerrit, so we would like to retain that aspect going forward. Gerrit is also a lesser problem when compared to bugzilla as, it does not require another account to be created for potential collaborators (a small win perhaps)

### Security CVEs still go through Bugzilla

## What is changing for users:
- Users are now encouraged to file github issues instead of using bugzilla
- All progress, discussions and updates would happen on the issue reported in github
- TODO: How to track if an issue is fixed in a specific release

## What is changing for contributors (non-maintainers/non-collaborators in github):
- Gerrit will not accept bug ID's, instead commits messages need to have one or more of the following,
- "{Fixes|Updates} #n...", where n is the issue number
- If an issue has more than one commit, the the last commit uses "Fixes", others use "Updates"
- If a commit addresses more than one issue, then repeat "Fixes" or "Updates" as required
- NOTE: Possibly rfc.sh may change to take in issue #'s that are updated or fixed as a part of the commit
- Feature page commits in the glusterfs-specs repository should reference the issue # in the glusterfs repository, for which the feature page is being written, as,
- "Updates gluster/glusterfs#n", where n is the issue number
- NOTE: As the feature page would/should never be the last commit, "Updates" would be used here
- Assignment
- Done by maintainers/collaborators, but anyone can start working on the issue, put in a comment on the issue (or submit your gerrit change referencing the issue), and the assignment will be addressed by the maintainer/collaborator/WorkerAnt(?)
- Labeling
- Added by maintainers/collaborators, but labels can be suggested in comments
- Milestone
- This is really for enhancements only, so if you are targeting an enhancement for a release, send a mail to gluster-devel regarding the same and the milestone would be reflected by the Maintainer/ReleaseOwner for the release
- Adding to Project boards
- As with milestones, when a feature is targeted for a release the Release Owner would update the corresponding project board appropriately

## Changes that maintainers/collaborators need to be aware of
- All of the above needs that non-collaborators/non-maintainers have, must be satisfied by maintainers, which includes,
- Assignment, Labeling, Milestone setting

## Release owner responsibilities
- Managing the release project lane in github Projects is something that the Release Owner would be responsible for
- TODO: What/when/how?

## Changes to backporting and erstwhile cloning
Backporting an issue to a older release does not require cloning the issue (like in Bugzilla), but instead leverages labels to track the same.

The following series of labels enable tracking issues across multiple releases,

- RequiredIn: Release-X.Y
- Denotes, across what releases this issue needs to be addressed in, and also means that it is not yet addressed in that release
- ComittedIn: Release-X.Y
- Denotes, across what releases a commit for this issue has been merged
- This label is the next phase for the release against which this is desired, hence will remove the older label "RequiredIn: Release-X.Y", when the last commit for this issue, on this release branch, reads "Fixes #n"
- ReleasedWith: Release-X.Y
- States across which releases a fix for this issue is released
- This is the state when a "ComittedIn: Release-X.Y" label moves to "ReleasedWith: Release-X.Y", post release of a major or minor update that includes this fix

## How does the weekly bug triage change
- TODO: Need inputs from the triage members
- Primarily, issues that do not have a component/experimental feature label assigned are targets for a triage, and those that have one of these labels are already triaged

## Changes to queries
- TODO: Possibly a few sample queries, and later a link to github documentation on how to generate more powerful queries

## Labels elaborated
Without bugzilla, the need to classify issues and track them against releases requires us to use github labels. This section details the various label categories that we intend to use for this purpose.

1) CB: XXX
CB -> Component Backlog
XXX -> Component name
Denotes an issue pertains to component XXX, and hence is automatically part of its backlog

2) Exp: XXX
Exp -> Experimental
XXX -> Component/Feature name
Denotes an issue pertains to an experimental feature/component, and hence is automatically part of its backlog

3) FA: XXX
FA -> Focus Area
XXX -> Focus area name
Denotes an issue aids in addressing a focus area, for list of focus areas see [2]

4) "RequiredIn: Release-X.Y" / "ComittedIn: Release-X.Y" / "ReleasedWith: Release-X.Y"
These labels are detailed in section [Changes to backporting and erstwhile cloning](#changes-to-backporting-and-erstwhile-cloning)

5) Enhancememt/Bug/ReleaseActivity
Enhancement: Issue is a requested feature
Bug: Issue is a bug
ReleaseActivity: Issue is a release activity tracker
- Example, release-notes for X.Y, testing update for component X, etc.
- Typically used by the release owners

## Issue lifecycle

Discussing the lifecycle of an issue requires some roles and their definition, as follows,

### Roles: User, Contributor, Collaborator, ReleaseOwner, WorkerAnt
- User is anybody who wants to open a github issue
- Contributors are folks who want to contribute code/documentation/specifications (any contribution basically)
- All Contributors are Users
- Collaborators are folks who have read/write permissions on the glsterfs repository, and have rights to modify issue metadata (labels, milestones, assignee etc.)
- Just for documentation purposes, Collaborators are segregated into other roles, Maintainer, FocusArea Owner, BugTriage, and referred with these role names when appropriate
- All Collaborators are Users (and mostly Contributors as well)
- ReleaseOwner is an (or multiple) identified Collaborator for a release, and has additional role to play
- WorkerAnt is a Collaborator, but a bot

### Lifecycle
Issue goes through 4 phases, *Open*, *WorkedOn*, *Released*, *Closed*. The roles defined above have differing responsibilities in these phases. The discussion below intermingles the two.

Anytime during the issue lifecycle, feedback and information maybe sought from any User, this is not elaborated below, and is an assumed responsibility of the User to provide the required feedback.

1) Open
- User
- Issue is opened by User
- Collaborator
- Labels issue as a Bug/Enhancement
- Labels issue against appropriate CB/Exp component/feature
- Labels issue against appropriate focus area
- If issue is a bug
- Assigns appropriate "RequiredIn:" tags to the issue
- NOTE: If issue is reported against master/mainline then this label need not be assigned always

2) WorkedOn
- Contributor handles commits against the issue
- NOTE: It is not mandatory that Collaborator has acted on an Open issue before a Contributor acts on it (IOW, contributors are free to start working on an issue without any labels and such)
- Issue is a Bug/Enhancement
- Submits patch referencing the issue
- WorkerAnt updates issue with patch reference
- WorkerAnt updates issue with assignee, if possible
- Issue is an Enhancement
- Posts required spec in glusterfs-specs
- WorkerAnt updated issue with spec reference
- Workerant updates issue with assignee
- Contributor announces intention on delivering the feature to the devel lists, for a specific release

- ReleaseOwner/Collaborator
- Accepts enhancement delivery intention (sent by Contributor to gluster-devel list) and marks Milestone on the issue

- ReleaseOwner
- Updates release Project board with identified issues targeted for a release

3) Released
- WorkerAnt
- Commit merged in gerrit and,
- Has "Fixes" in message
- Checks branch against which commit is merged, and updates issue with "ComittedIn" tag
- Has "Updates" in message
- Updates issue with status
- Commit merged to master and no other release based tags on issue
- WorkerAnt **Closes** issue
- NOTE: One of the collaborators need to merge the issue, so any additional releases that the issue needs to be merged in, will be updated by the collaborator, hence preventing a close due to a lacking label

4) Closed
- ReleaseOwner
- Updates "ReleasedWith" tag for issues when a release is made including the commits for that issue
- Further **closes** issue, if there are no pending "ComittedIn" or "RequiredIn" tags for the issue
- IOW, when a major or minor release is made, a query based closing of issues need to happen

- Collaborator
- Closing issues when a release is EOL'd or moving it to master etc.

## Links
[1] 3.10 release announcement, as reference to release scope tracking via github
- http://lists.gluster.org/pipermail/gluster-devel/2016-November/051584.html

[2] Gluster gerrit instance: https://review.gluster.org/

[3] Backlog and feature planing mail: http://lists.gluster.org/pipermail/maintainers/2016-November/001726.html

## Questions:
- We have *many* components in Bugzilla, do we really need these 3x in GitHub issues (CB:, Exp: and FA:)?
- No we do not need 3x, CB is for existing components, Exp is for new experimental components, FA is Gluster "Focus Areas"
- Example DHT is a CB, SELinux support is Exp, Server side replication is a focus area
- Further these labels and categories was elaborated a couple of months back here [[3]](#links)
- Rarely would a an issue have a CB+Exp (or almost never). An issue can have multiple FA labels though (and also multiple CB labels, in case it spans across components)
- The backporting process looks difficult to keep track of. When do issues get closed? Should closed issues still be used for backporting to stable releases?
- I am working on a dummy project/repo that will deomnstrate this, which should help in understanding this better
- An issue that is closed **will** be used for backporting
- The 'TODO: needs input from triage members' is mainly asking on gluster-devel. All developers are expected to follow the triage guidelines from the documentation.
- Can we get some help here, to first check what we would need to provide the tirage team as queries, from there it should be easier. I would like to close that as the first step, than just throw this out to devel
- *Add your questions and queries here*