E Version control workflow

E.1 General workflow

  • Set up a “work-space” folder in your project folder.
  • Each developer sets up a sub folder in the “work-space” folder - this should be named to identify the user eg their initials.
  • Each developer will need to clone the project’s github repository into their work-space (if the project has not been set up on github yet then it will need to be created).
  • Developers should work in their own work-space.
  • Developers should switch to the agreed development branch (this may need to be set up).
  • Developers should fetch/pull any changes from the repo.
  • Developers should make edits and commit and push then to the development branch.
  • Issues should be added to the Issues section on the github repo and assigned to others as needed.

E.2 Notes

  • We are mainly using the github desktop app as our main way of pull/push/committing rather than git – it has a nice front end and it’s probably easier and more intuitive to use than cli git. However git or VS code are alternatives.
  • We are using the github issue section on github to record issues, assign issues to people and track progress (when making a commit you can include a tag to the issue so the commits are shown in the issue – this allows others (eg a reviewer) to get the code that’s changed quickly)
  • We have found a single development branch as the most easy to use approach when working collaboratively – we should merge this development branch into the main branch at key stages.
  • We have found that if possible developers should avoid working on the same file at the same time - otherwise merge conflicts can occur - it is possible to resolve these but this can be confusing!

E.3 Commits

  • Commits should ideally relate to a single issue or piece of functionality (this makes it easier to revert if the change causes problems).
  • Commits should be well labeled (makes it easier to find a change later).
  • Add more detailed information in the commits desciptions (further comments or technical detail).

E.4 Setting up the project repo for first time

  • As above the initial workspace should be set up and subarea for the coder setting up the repo.
  • It is important to set up a .gitignore file at the start of the project so we do not include any data or build tools (like node_modules folder that Sam mentions) – this will be project dependant but somewhere like (https://github.com/github/gitignore can be a good starting point – depending on the language(s) you are using. Gitignore allows us to control which files/folders are to be excluded from the github index (which tracks files) but its important to do this early (ideally with the first commit) as it can be difficult to then remove these files/folders from the index.
  • It is useful to allow add a README.md file to set out what the project is about and any useful information.
  • Github desktop or git can be used to set up a new repository in the folder.
  • The repo should be added to the GADHUB organisation.
  • Development branch(es) should be added to your repo .
  • Developers can be given access to the repo via the repos Settings > Collaborators and Teams menu.