Developer workflow - ral-facilities/scigateway GitHub Wiki

Workflow

Select a story from the board.
Pull the latest version of the master branch
Create a branch from there called feature/{insert general name of story}-#{story number}
Put the story into In Progress on the board
Repeatedly during development:
1. Develop code/write tests
2. Ensure all tests pass
3. Run linter and fix issues
4. Commit - ideally, each commit message should have the issue number included, so that we can track the code related to resolving the issue
5. (optionally) push to origin
Merge origin/master into your feature branch.
Run unit tests
Check impact on coverage
Run e2e tests
Push to origin
Make a pull request - the PR description should also point to the relevant issue
Put the story into In Review on the board
Get the pull request reviewed, if more work needs to be done go back to step 4.
Wait for the automated build (if it exists, otherwise the reivewer should do these steps)
Once a pull request is approved then it can be merged back into origin/master
Wait for the automated build for the merge in to master to pass.
Move the story to Done and close the issue.

Story State Transitions

Stories move to the Backlog when they need to be done but not in the current sprint.
Stories start in To do when they are first created (note that when creating a new issue you must add it to SciGateway/DataGateway project in the drop-downs on the right hand side of the issue description). If the issue is not intended to be worked on during the current sprint, then please move the issue to Backlog
Stories move to In Progress when development work is started on them. A developer should be assigned to the issue at this point.
Stories move to In Review once they are dev-complete and a pull request has been made. New code must remain on the feature branch until the pull request is approved.
Stories move to Blocked when the issue is unable to be completed due to external issues.
Stories move to Done once the pull request has been approved and merged back in to master, thus indicating the functionality described in the story has been added to the system. The story can be closed at this point.

Branching Strategy

When working on a new feature the branch should follow the naming convention feature/{insert general name of story}-#{story number}. This indicates it is new functionality as well as linking it to the story (for potential future requirement tracing)

If working on a bug from a previous story then the branch should follow the pattern bugfix/{general name of bug}-#{story/bug number}.

Code Development and Testing

Stories should be small and thus (mostly) only affect a small number of files. Development should be focused on delivering only the functionality outlined in the story and if more changes are identified then these should be added to a new story; this facilitates being able to track how much effort is needed as well as showing the rate of discovery of what is needed to deliver the system.

All code should be tested as much as possible, this helps provide confidence when refactoring and means that ultimately code development is faster in the long run. A high level of testing also means that bugs are likely to be spotted earlier which reduces the cost of fixing it. Such a high level of testing is not achievable manually without a lot of person-effort and very difficult to do in a repeatable way - therefore there should be as much automated testing as possible.

Primarliy testing should be focused on unit testing where individual classes and functions are tested as these are quick and can cover most of the functionality. Integration tests may also be required to see how components interact and check they work correctly together. Top level testing to check workflows and use-cases is generally done with system testing - there are likely to be fewer of these as they are slower but probably at least one per story (to check the feature works).

Ultimately, there may still be a certain level of manual testing for things that are too costly to automate - but it is better to keep this to a minimum so testers can do exploratory testing and find bugs that occur outside of the normal paths through the system.

Preparing for a Pull Request

As a developer, when you think the functionality for a story is complete then

you should merge in the current state of master into your branch (note, by doing it this way round you ensure master is always in a good state)
run the linter to make sure there are no violations
ensure the tests pass (unit, integration, and system/e2e)
make sure storybook still works and any required component demos are added
make sure the documentation is up-to-date
push to the repo

At this point you can then make a new pull request.

Pull Request Procedure

When a branch is ready to be merged back in then you should create a pull request in GitHub. The description should contain:

A general description of the changes in the pull request
A link to connect the PR to the issue (connect to #{issue number} or Closes #{issue number} if your PR fixes the issue)
A method for testing the changes, particularly if they are visual in nature (e.g. describe which StoryBook story to look at or which url to visit). You may also want to consider adding a screenshot of the changes.

Generally the PULL_REQUEST.md template in the .github folder provides a lot of this structure and you just need to fill in the parts of the template.

If this is your first time reviewing then you will need a development environment set up first, see Setting up a Development Environment

Before approving, a reviewer should:

review the code
ensure the build passes
assess the impact on code coverage
run the method for testing as described by the developer as assess the visual impact of the changes