Branches & Issues & Versions Management
The HappyTree API has a contribution organization in a very simple way, without bureaucracy. All of this is done to further encourage the act of contributing by third parties.
If you want to contribute, you just need to fork the project and work on the current version of the project, which is specified in every reported issue through the milestone section.
Every contribution is inserted within the Issue context which can be reported by anyone and this Issue is associated with the actual Milestone of the project. Each Milestone represents a version number (the current Milestone is 2.0.0), the official API version being developed at the moment.
Also, for each Milestone, there will always be its respective Branch, in this case named 2.0.0, and every development must be done under this branch, known as the version branch. So, there will always be a connection among Issue, Milestone and Branch and this link is identified by the current version of the API being developed at the moment.
Each milestone represents a version of the project and has an estimated date to be concluded. The project can have the same number of milestones as the project versions, currently being at version 2.0.0.
The milestone is a concept used only for internal purposes; external collaborators cannot manage it.
Any collaborator can create new issues. There are two ways of creating new issues:
- By using a template;
- By creating an empty issue.
When the collaborator pushes the button to create a new issue, they will be directed to a page where they can specify the issue type through a template or simply create a new empty issue.
By selecting a template, all required inputs will be automatically generated for the collaborator to fill in, so there are no concerns in this case.
Another option occurs when the collaborator decides to create an empty issue without using templates. To do this, the collaborator must follow some rules for better comprehension and organization of ideas. In the title, simply add the prefix corresponding to the current Milestone version, for example: [2.0.0] - Print Hello World. It is very important that this prefix ([2.0.0] -) is included.
In addition, it is only necessary to define the type of Issue to be created. Each type is represented by a GitHub Label. Below are the labels that define what each issue represents:
| Label | Description |
|---|---|
| type: adaptive | Request/feature change issue |
| type: bug | Bug found |
| type: documentation | Issue for API documentation and .md files |
| type: enhancement | Issue for improvements and refactoring |
| type: feature | Issue for new functionality/feature |
| type: question | I have a question |
| type: suggestion | Suggestion about any topic |
| type: test | Issue for unit tests |
| type: urgent-bug | Notification for a high-priority bug |
Regardless of the issue type, the collaborator is free to organize their ideas as they wish, with the exception of type: bug and type: urgent-bug issues. These types require special treatment in their descriptions, as it facilitates the bug-fixing process when an issue includes the following topics, in this order:
- What was done;
- Describe in an objective and summarized manner what was done.
- What happened;
- Describe in an objective and summarized way what occurred.
- What was expected to happen;
- Describe in an objective and summarized way the expected result.
- Steps.
- List and detail the step-by-step actions that were performed, preferably with screenshots.
When a collaborator publishes a new issue, it does not mean that the issue will be addressed immediately, as it will first receive feedback from the HappyTree Team, represented by black labels. These labels can be:
| Label | Description |
|---|---|
| status: waiting-for-triage | Issue that has not been reviewed yet |
| status: accepted | Accepted issue |
| status: declined | Declined issue |
| status: declined-duplicate | Declined due to duplication |
After the collaborator has their issue accepted, the issue will be included in the next release. The collaborator can then track the issue through the white labels provided by the HappyTree Team over time:
| Label | Description |
|---|---|
| phase: backlog | Issue in the backlog phase |
| phase: in-progress | Issue in progress |
| phase: testing | Issue in testing phase |
| phase: done | Issue completed and scheduled for the next release |
The HappyTree API strategy for handling development branches is based on versions. In other words, a version number drives the relationship among Issues, Branches, and Milestone.
This workflow strategy is known as Release Flow, where, from the main branch, a dedicated branch is created for each release. For example, the 2.0.0 branch is created under the main branch.
In this approach, new features and fixes are developed in dedicated branches and merged first into the 2.0.0 branch before being merged into main, ensuring a clear separation between stable and development code.
While work is in progress on a specific version, all commits must be made under the corresponding snapshot version branch. In the example of v2.0.0, the branch name would be 2.0.0-SNAPSHOT.
Knowing the current version being developed, as defined by the milestone, there will be only one branch directly below main, and its name will represent the current version. All development, performed by the HappyTree Team and external collaborators, must be based on this snapshot branch. In the example of v2.0.0, the main branch will have only one child branch called 2.0.0, and below this branch there will be only one branch called 2.0.0-SNAPSHOT.
Below the snapshot branch, 2.0.0-SNAPSHOT, the collaborator may create their own branch without restriction. However, as a recommendation, it is preferred that the created branch follows the format: 2.0.0-issueId, where issueId is the GitHub Issue ID reported by any user. For example, if there is an Issue #100, the branch name would be 2.0.0-100.
The user who wishes to contribute follows a workflow partially described in the previous sections. The workflow consists of creating or working on an issue that belongs to a version represented by a milestone, and whose commits are made on a branch that is nested within another branch representing that version.
The following workflow consists of:
- The user who wishes to contribute creates a new issue or opens an existing issue;
- The user views or associates the current milestone (version) being developed;
- If the user created a new issue, they must wait for a response confirming whether the issue was accepted;
- If the issue is accepted, the user forks the code;
- The user creates a branch from the current version branch. For example, for the v2.0.0 milestone and issue ID 100, the user creates a branch named 2.0.0-100;
- The user submits a pull request to the version branch;
- If the user's pull request is accepted, they can track their changes through the white label feedback, indicating whether the issue has received the done label.