How to collaborate with me on GitHub

info

This page covers the Git and GitHub mechanics: setting up, forking, branching, committing, and pushing. The workflow itself — how to pick an issue, scope it, and get a change reviewed — is in Contributing to my projects.

Why I use GitHub for collaboration

I am a strong advocate for using GitHub as a collaboration platform for research projects. GitHub provides a range of tools and features that can help streamline the research process and enhance collaboration among team members. I believe that GitHub can be a powerful tool for version control, issue tracking, code review, and project management. I am not a computer scientist so if you have any suggestions on how to improve our workflow, please let me know.

How to get started with GitHub

1. Create a GitHub account: If you don't already have a GitHub account.
2. Familiarise yourself with GitHub: If you are new to GitHub, I recommend taking some time to explore the platform and learn about its key features.
3. Install Git: Git is a version control system that is used to manage code repositories on GitHub. You can download Git from the official website.
4. Fork and Clone the repository: Once you have a GitHub account and Git installed, you can clone the repository for our research project to your local machine using the following command:

   git clone https://github.com/<organisation>/<repository>.git

5. Create a new branch: Before making any changes to the codebase, create a new branch to work on. This will help keep your changes separate from the main codebase and make it easier to track your progress.

note

Use a descriptive branch name that reflects the purpose of your changes. For example, if you are working on a new feature, you could name your branch feature/new-feature.

6. Switch to your new branch: Use git checkout <branch-name> (or git switch <branch-name>) to move onto the branch you just created before making any changes.

7. Make your changes: Once you have created a new branch, you can start making changes to the codebase. Be sure to follow the project's coding conventions and guidelines.

tip

Every project has its own conventions — read them before you start. For Python projects we use ruff for formatting and linting, and run it through pre-commit. See Collaboration on Python Projects for the details.

8. Commit your changes: After making your changes, commit them to your branch using the following command:

   In Git, a commit refers to the state of your code at one specific point in time. Commits carry metadata (author, timestamp, commit message, etc.) and are used for saving progress, stating changes, and merging developed pieces with others' work.

   • A Good Commit should:
     • A commit should be atomic - it has to represent one and only one logical change. Do not mix several independent changes in one commit.
     • Descriptive - the commit message should be descriptive and concise. It should explain what the commit does and why it is necessary. It should be written in the imperative mood.
     • Follow Conventional Commit Guidelines - the commit message should follow the Conventional Commit Guidelines. This will help to automate the release process and generate a changelog. These guidelines are usually structured as a type (e.g. feat, fix, chore, refactor, docs), a short summary, and occasionally a longer explanation.
     • Tested - the commit should be tested and should not break the existing codebase. It should not introduce new bugs.
     • Properly scoped - for example, if you are fixing a bug then the commit message should start with fix:, and it should fix the bug in a single commit. If you are adding a new feature, then the commit message should start with feat: and it should add the feature in a single commit.

   # Good commit
   git commit -m "feat(login): Add user authentication"
   # Bad commit - missing conventional commit standards, and includes two logic changes
   git commit -m "Add user authentication and update UI styles"

   • A Bad Commit is:
     • Too big - it is too big and includes several independent changes.
     • Not descriptive - the commit message is not descriptive and does not explain what the commit does.
     • Vague - the commit message is vague and does not provide enough information about the changes.
     • Not tested - the commit contains incomplete code and/or is not tested and introduces new bugs.
     • Combines unrelated changes - the commit combines unrelated changes in a single commit.

9. Push your changes: Once you have committed your changes, push them to the remote repository using the following command:

    git push origin your-branch-name

10. Open a pull request: after pushing your changes, open a pull request on GitHub to propose merging them into the main codebase.

    Most repositories ship a .github/pull_request_template.md, so the structure will be filled in for you. What belongs in that description, the AI use section, the screenshots required for interface changes, and the order in which a pull request gets reviewed are all covered in Pull requests and review.

11. Review and merge: your pull request is reviewed first by other contributors, then by the AI reviewer, then by a maintainer. Never merge your own pull request — see Pull requests and review.

12. Stay up to date: be sure to pull the latest changes from the main codebase regularly to stay up to date with the project's progress.

13. Collaborate: GitHub provides a range of collaboration tools, such as issues, projects, and wikis, that can help streamline the research process and enhance collaboration among team members. Be sure to take advantage of these tools to stay organised and communicate effectively with your team.