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. Everyone is considered a leadership team member during the priorities meeting.

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

Git Branches and Tags

Git Branches and Tags point to the point in the history of the source code.

• 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 rebased onto production branch through pull requests within 2 weeks from getting open.
• production - the bleeding edge; contains all features and bug fixes that passed testing. All feature branches are rebased into this branch.
• Tag - once a month, production branch undergoes general testing, at which point it is tagged and a new version number is assigned.

DockerHub Tags

DockerHub tags point to the built image of a certain Specify 7 version.

Each Git branch and Git tag gets a tag in DockerHub with the same name. The only exception is production, which is called edge.

Issue Creation

[UX Team] New issues should follow the "Bug Report" or "Feature Request" template. All applicable fields in the template should be filled out. In case of bugs, the issue description should include information on how to test the fix and what is the expected behaviour.

It is recommended that issues are created using

If an issue needs to be ignored and hidden from the list during the priorities meeting, remove the pri:unknown label

(optional) [UX Team or Developers] Additionally, issues can be assigned to one or multiple projects either as soon as they are created, or during the priorities meetings.

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

Priority

[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. Go over all the issues that have a pri:unknown label: https://github.com/specify/specify7/issues?q=is%3Aissue+is%3Aopen+label%3Apri%3Aunknown

[Leadership] These issues should be assigned to projects, if they are not assigned yet, and moved into the To Do column in each project. Additionally, pri:unknown label should be removed and some other priority level must be set (pri:low, pri:normal, pri:high)

[Developers] Developers must go over all pri:high issues as soon as they come up. After that, pri:normal and pri:low issues should be tackled. 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).

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

Dev Testing team is supposed to review pull requests assigned to them after automated tests have passed.

After testing the change, the pull request should either be approved or rejected. If it is approved, it may be appropriate to add a brief description of how it was tested. If it is rejected, steps taken to reproduce the issue would be helpful.

If a pull request is rejected, go back to the "Fixing" stage. Later, when testing, UX Testing team may want to look at the comment attached to the previous review.

List of pull requests assigned for approval by Dev Testing team.

Once Dev Testing team approves changes, or if a pull request does not require a review from the Dev Testing team, the pull request is automatically deployed to the test server. UX Testing team members should open the test server once a day to verify outstanding pull requests.

Deploying

After the Dev Testing team and the UX Testing team approved the issue and automated tests are completed successfully, the issue is automatically rebased onto the production branch.

The production branch always has the most recent bug fixes and issues improvements.

Once a month, production branch undergoes general testing, at which point it is tagged and a new version number is assigned.

Users should always update to the latest tagged version. If there is a bug on the tagged version and, after being reported, it gets fixed on the production branch, the user should update to the edge DockerHub tag