Getting set up
The process documented here relies on a particular configuration of GitHub features. While other arrangements are possible, this one attempts to keep things simple for a small team. First, we assume that the team will only be sharing a single repository. That is usually a reasonable assumption for a small project, or for the maintenance of a single application.
The first step is to create an organisation. While many GitHub features related to issues, projects and collaboration are available in personal repositories, many external integrations rely on the existence of an organisation as the main container object. This is true, for example, for integration with Axolo which helps to streamline pull requests.
The next couple of steps are to create a new repo and make sure that the development team has access.
Issues
Requirements are recorded using the GitHub issues functionality. When a new requirement is identified, and issue is created with a high-level description - just enough to allow someone to understand what it is about. It is labelled either as a bug if it involves a fix to existing code, or as an enhancement if it is related to the development of a new feature.
When it is selected for attention, an issue may be broken down into a series of smaller tasks.
Project
GitHub allows you to create projects to organise teamwork. One of the main features of a GitHub project is the task board. We assume that there will be a single open-ended project that will be used to manage progress on all tasks. To make an issue visible on the project board, it must be added to the project.
The project board has four columns that categorise issues, tasks and pull requests (see below) as described in the table:
| Column | Issues and Tasks | Pull Requests |
|---|---|---|
| To Do | New items, not yet assigned to a developer | --- |
| In Preparation | Assigned and working towards Ready | Awaiting code review |
| In Development | Code changes in progress | Approved by reviewers |
| Done | Complete according to the DoD | Branch merged and code migrated |
NB. Before moving an issue or task from In Preparation to In Development, the developer needs to get approval from the product owner or some other person with responsibility for the overall product development.
Branches and pull requests
All code changes (and changes to the documentation) related to an issue are done on a specially-created code branch. GitHub provides various ways to create a new branch, but in general, the simplest approach is to use the integration features built into development tools such as PyCharm.
Once all the changes are made and unit testing is complete, the developer checks the changes into GitHib and creates a pull request. This is a signal that the developer thinks the code branch is ready to be merged. However, before that can be done the code needs to be reviewed to check for any defects that the developer may have overlooked. Following a review, a task or issue may be reopened to allow the developer to do some more work. If everything is OK, the branch is merged, any code conflicts are resolved, and the changes are migrated to the integration environment.