Issue Workflow

Specify 7 Issue Workflow

This document formally documents the workflow of using the GitHub issue tracker for handling Specify 7 bugs and feature requests.

Square brackets before a sentence indicate whose responsibility it is (UX Team, Developers, or Leadership)

Definitions

Teams

• UX Team - User Experience Team; responsible for making sure the implementation complies with the requirements and that it is intuitive.
• Developers/Dev Testing - Developers involved in the project. Generally, if a pull request is assigned to a Dev Testing team, it should be revied by somebody other than the person opening the pull request. Leadership - people in charge of setting priorities and evaluating ideas.

Notice, the teams may overlay and one person can be a member of multiple teams. Teams are primarily meant to set expectations about responsibilities.

Branches

• Feature - can be named like issue-### where ### is the issue ID in case of small features and bug fixed, or more descriptive, like query-list-refactor, for bigger branches. Ideally, feature branches should be short-lived and get merged through pull requests within 2 weeks from getting open.
• next - the bleeding edge; contains all features and bug fixes that passed testing. All feature branches are merged into this branch.
• stable - the most stable branch. Feature branches that contain bug fixes should also be merged into stable. next is merged into stable once a month after undergoing general testing

Issue Creation

[UX Team] New issues should be entered into the tracker and assigned a type: label (type:bug and type:enhance are the most common).

[Developers] Additionally, every issue must be assigned to one or multiple Projects.

Newly assigned issues automatically appear in the Unsorted column of the project board.

Priority

[Leadership or UX Team or Developers] Once a bug is reproduced or the enhancement is reviewed and approved as a priority, it is moved from the Unsorted into To Do column in each project it belongs to.

[Leadership] Every Monday there should be a brief priorities meeting to identify the issues that should be fixed, and which of those must be fixed the same week. These issues should be moved into the To Do column, with issues for that week being assigned to respective people or teams.

[Developers] Developers must aim to finish assigned issues by the end of the week. If small issues come up during the week, they can be fixed without consulting the Leadership team.

Fixing

[Developers] While the issue is in the process of being fixed, it is moved from the To Do to the In progress column.

[Developers] It is recommended that each issue is fixed on a separate branch and that a draft pull request is opened for each issue that reaches this stage (don't forget to link the pull request to an issue).

[Developers] In some cases, multiple issues can be linked to single pull requests. For example, if one change fixes multiple issues, or there are multiple small issues (design changes, typos). Though, we should aim not to have giant pull requests, as those are hard to test and review. That would also help keep branches from diverging too much. Also, a maximum of 10 issues can be linked to a single pull requests

Testing

[Developers] After the issue is fixed, it is moved from the In progress to Ready on branch column.

[Developers] The draft pull request is converted into a regular pull request. Developers are responsible for rebasing the feature branch of next before it gets tested.

[Developers and/or UX Team] Pull requests must be assigned to at least one member from the Dev Testing and UX Testing team, if applicable (it depends on the nature of the code changes).

Links to always up-to-date lists of pull requests that are assigned for approval by Dev Testing and UX Testing teams.

Dev Testing team is responsible for code review, while UX Testing verifies the behavior of the feature.

Deploying

After the Dev Testing team and the UX Testing team approved the issue and automated tests are completed successfully, the issue is automatically merged into the next branch. If a pull request is related to a bug fix, it should also be merged into stable.

The aim of the next branch is to strike a balance between the newest features/bug fixes and stability.

next branch should undergo general testing once a month, at which point it gets merged into stable.

stable branch focuses on stability and bug fixes, rather than new features. New features are merged into it from next once a month. Bug fixes are merged into it as soon as they are made.