# github issues for features and [major fixes](#appendix-a)
For release-3.10 we used github projects and milestones to track scope of the features that were to be a part of the release[^1]. As a result, during 3.10 release, features needed duplication in github as well as in bugzilla as our existing automation/scripts could only cope with bugzilla.

From release-3.11 **onward**, we intend to optimize this workflow, by **NOT** needing to **duplicate features** or major fixes in bugzilla and retain them only as github issues.

> NOTE: Feature or major issues that need to be backported will still need a bug filed and follow the bugzilla workflow, as features should never (or rarely) need backports

This document details the entire change (started since 3.10) to the development workflow.

> **NOTE:** The rest of the document refers to issues as features and vice-versa, 'major fixes' is not explicitly used further but is implied when using these terms

## Current workflow for feature submissions
Our current worflow involves part of, or all of, the following 6 steps for a feature submission,
1. Propose a feature in gluster-specs[^2]
2. Propose said feature for release-X.Y
- Typically done sending a github PR (Pull Request) to the glusterweb repository[^3]
3. File a Bug to track various commits to glusterfs repository for the feature
- Using our bugzilla[^4] instance
4. Submit code for the feature using gerrit[^5]
- Mention the bug created in the previous step, in the commit message, for the various patches submitted for this feature
5. Submit documentation for the feature at glusterdocs[^6]
6. Submit release-notes for the feature, (example[^7])

## Proposed workflow for feature submissions
Following is the proposed workflow, where a **single github issue #** would be used across 3 repositories and possibly multiple code commits to track feature completion,

### This is a very short version (longer version follows)
- Create an issue for the proposed feature in glusterfs github
- Propose and get your feature accepted for a release, by posting to [e-mail] with the relevant issue # and details
- Use issue # in **all** commits against that feature, like commits to spec or code or docs repositories
- Reference the issue in commits, as "Updates #n" or "Fixes #n", use Fixes with the last commit for the feature, so that when that gets merged, the issue is automatically closed
- Reference the issue from non-glusterfs repositories as "{Fixes|Updates} gluster/gusterfs#n"
- If a feature needs to be backported (which should ideally never happen) then create bugzilla for the same, and follow the bug workflow of backporting the same
- Example: https://github.com/gluster/test/issues/9

### Here is a longer version...
> NOTE: Screen shots in the following examples use the gluster/test repository, in reality this would be gluster/glusterfs

1. File a github issue for the proposed feature[^8]
**Example: Filing an issue**

2. Elaborate the details of the feature in a specification @ **gluster-specs**[^2]
- The **commit message** should contain a reference to the github issue as, **"Updates gluster/glusterfs#n"**, where n is the issue number (For example, #9 in the screenshot above)
- In the rare event that the spec is the last commit, change the "Updates" to "Fixes" above
**Example: Referencing a commit to point to the issue**

**Example: Referenced issue updated in github**

3. Propose said feature for release-X.Y
- Send a mail to <[e-mail]> giving details about the feature and pointing to the issue # filed, in the mail,
- Clarify if this is a feature or a major fix
- If possible, clarify which component(s), focus areas it may impact
- See [Appendix C](#appendix-b) for component and focus areas
- Gluster **maintainers** and/or **release owners** will take over from here,
- The relevant maintainer will add the required labels to the issue in github
- Mainatiner will add the milestone as per the requested release
- Release owner will update the github project lane for the release with the intent to deliver the said feature (basically drag and drop it to the project lane)
- Maintainer and release owner, will respond over mail if the feature is accepted for the proposed release

**Example: Issue updated with labels and milestone**

**Example: Issue appears in the milestone query**

**Example: Issue is added to the project lane for said release**

4. Submit code for the feature using gerrit[^5]
- The **commit message** should refer to the github issue as, **{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
5. Submit documentation for the feature at glusterdocs[^6]
- The **commit message** should refer to the github issue as, **{Fixes|Updates} gluster/glusterfs#n ...**, where n is the issue number
- Ideally, documentation is updated at the end of feature development, so this maybe the commit that actually states Fixes for the issue #
6. Submit release-notes for the feature (example[^7])
- The **commit message** should refer to the github issue as, **{Fixes|Updates} #n ...**, where n is the issue number
**Example: Last commit for said issue uses "Fixes"**

**Example: Above commit closes the issue**

## Gerrit script updates needed
> NOTE: This section is more for changes that we need in our infrastructure with the new workflow, contributors and users can pretty much ignore details here (if not interested)
1. Update WorkerAnt to post to a github issue as soon as a patch is posted against the same
- Change: https://github.com/gluster/gerrit-hooks/blob/master/patchset-created
- This is required, so that we do not have to wait till a merge of the commit, for the details to appear against the issue
- This needs to change to pick up commits posted against glusterfs, glusterfs-specs, as these are controlled via gerrit
- For glusterdocs however, only when the documentation PR is submitted and accepted, will the issue be updated
2. Update rfc.sh to check/request issue # when a commit is an "rfc"
- Change: https://github.com/gluster/glusterfs/blob/master/rfc.sh
- This is more a helping hand for the process, when a bug ID is not entered, it would be helpful to check if the commit message has a Fixes or Updates issue# comment, else prompt and edit the commit message accordingly
- For glusterfs-specs, we use git-review instead of rfc.sh, so a test needs to be enforced somewhere in that workflow for issue# presence (even reviewers can request for the same if it is missing)
- Further, for rfc changes, we can auto add "updates" instead of asking in rfc.sh if it is an updates vs fixes, as that can be sorted out in the review
3. Does Jenkins compare-bug need an update?
- Unsure if this needs an update for the above, https://github.com/gluster/glusterfs-patch-acceptance-tests/blob/master/compare-bug-version-and-git-branch.sh
4. Optional gerrit to provide links to github issues
- Like gerrit provides in the BUG value a link to bugzilla, is it possible to provide a link to an github issue? That would be quite nice, instead of having to form the URL every time
- Example from the go gerrit site: https://go-review.googlesource.com/#/c/37148/

## Release scope and roadmap pages for the community
As mentioned earlier, release scope till now was maintained as web pages[^3] that needed PRs to update.

We now use github projects to share our roadmaps. Here[^9] is a view of the same. Each release gets its own lane, and has a list of features targeted for that release.

## Release scope management by a release owner
This section further details the workflow involved in maintaining a release project lane by the release owner.

1. Contributors start posting to <[e-mail]> stating features that they would like to target against certain releases
- As the release schedule is known up ahead, contributors can post features that they are working on for future releases than the current one
2. Once a proposal is accepted, the issue that it reflects is marked against the appropriate milestone
- By a maintainer or the release owner
3. The release owner is responsible to add the issue to the release lane in the releases project board[^9]

## Appendix A
### What are major fixes
Fixes that are almost features, but were not implemented earlier and hence are reported as bugs now.

Another way of looking at major fixes would be to see if these would be backported to older releases or not, if not, then they are good candidates to appear as major fixes in github.

A lot of technical debt for example that mask themselves as bugs come into this category, among other things. Another good example is some consistency layers that were missing in some xlators, these are bugs, but work on them is more than bugs and we want to call these out in the project planning pages. These are just examples to clarify this topic.

## Appendix B
### Component and focus areas
#### github component labels
The component labels are of 2 forms,

- CB: XXX
- Used for components that are non-experimental (e.g distribute, replicate, disperse, posix)

- Exp: XXX
- Used for components that are experimental (e.g glusterd2, JBR, SELinux)

#### github Focus Areas and their labels
These are the current Gluster focus areas,
- Testing Improvements
- Technical Debt
- Server Side Replication
- Scalability Improvements
- Performance Improvements
- Must Fixes
- Developer Experience
- Container Integration
- Client Side Caching

Focus area labels are prefixed with FA: in github, example "FA: Technical Debt"

[^1]: Gluster-devel mail *"Announcing release 3.10 schedule"* http://lists.gluster.org/pipermail/gluster-devel/2016-November/051584.html
[^2]: Glusterfs-specs https://github.com/gluster/glusterfs-specs
[^3]: Example from glusterweb repository holding the 3.8 release scope: https://github.com/gluster/glusterweb/blob/master/source/community/roadmap/3.8/index.md
[^4]: Glusterfs bugzilla (new bug page): https://bugzilla.redhat.com/enter_bug.cgi?product=GlusterFS
[^5]: Gerrit instance for glusterfs: https://review.gluster.org/#/
[^6]: Glusterdocs repository: https://github.com/gluster/glusterdocs
[^7]: Example release notes submission: https://review.gluster.org/16524
[^8]: Glusterfs github issues: https://github.com/gluster/glusterfs/issues
[^9]: Glusterfs release project board: https://github.com/gluster/glusterfs/projects/1