For this project, I suggest to use a feature branch workflow in git. Furthermore I recommend to do the merge with the main branch through pull requests on GitHub at least once a week and have someone else accept requests.
Feel free to skip the rest of the document if the above information makes sense and you agree with it. In the following sections I will describe how to work with git and GitHub in more detail and provide some reasoning for the suggested workflow model.
Git is a software that allows to keep track of different versions of source code in the same directory. This type of software is called source code management software (SCM). Imagine, you have a set of scripts that work well and that you use every once in a while, but you want to test a new idea for a data analysis. Without SCM you would probably create a new directory, copy all the files there, and start developing the new version there. With git you can stay in the same directory and use git branch to switch between different versions. Similarly, if you know that your script worked six months ago but doesn't work right now, git log would allow you to have a look at what changed since then and recover this earlier version. While git is already useful for a single person, it was designed as a tool to collaborative develop millions of lines of code between thousands of individuals. Since then it has been used for a large variety of different use cases.
At its core, git is a command line tool to keep the different versions of code organized and is the most powerful and complete client software to interact with the files. In addition, there is a variety of graphical user interfaces (GUIs) to make git more accessible. In my initial email I had asked about your git experience and preferences. Back then, a few responded that they had used the software GitHub Desktop. If you don't have another preference, I would suggest that you install this free git client from the website -- it is available for Linux, MacOS and Windows. The rest of the documentation will use GitHub Desktop and git for the examples. Please note, that the client GitHub Desktop (a git client) is something completely different from GitHub (the website hosting git repositories) -- but yes, the shared name has lead to confusion in the past…
GitHub is a webservice where people can host their git projects. Once you share a git repository on GitHub, you can use the website to look at the content of the directory, switch between different branches, and have some other basic interactions with the files in git. In addition, GitHub provides some project management for the git repositories. Most notably you can open and track issues (and other code review and bug tracking tools), run tests and verifications on your code (so called Continuous Integration and Continuous Delivery, CI/CD features), and use boards that are inspired from Kanban to manage long-time goals. All of theses additional features are well integrated with the code. GitHub is just one, although probably the most well-known webhoster for git repositories. For this project, we will use a subset of GitHub's features to manage the project and code.
Other notable examples for git webhosters are GitLab, Gitea, Bitbucket, GNU Savannah, and SourceForge -- some of these services also support other SCM systems like Mercurial or Subversion.
Across git, any git client like GitHub Desktop, and git webhosters like GitHub, there is a shared terminology. Here a brief list with some comment on the relevance for our project. There is an excellent free book available on the git website and here we will only touch on some parts from chapters 2 and 3, but if you have questions or want to read more, this book is always a good reference.
If you want to convert a normal directory into a git repository, you will need to initialize the project. This can be done by navigating to the directory of your project and then type git init. In GitHub Desktop you can achieve the same with File → New Repository. For this current project you don't have to do this, the project has already been initialized.
Instead of creating a new git project, you can also git clone a project. This means you pull an existing git project from a remote webhoster, for example from GitHub. If you got to the repository at https://github.com/reiserlab/optic-lobe-connectome, you will see a green Code button. A click will give you the URL for cloning the code. You can either use it on the CLI by typing git clone [email protected]:reiserlab/optic-lobe-connectome.git or you can use the URL in the GitHub Desktop client by clicking File → Clone repository → URL. This will create a copy of the project locally on your computer, at whatever location you choose.
Any file from inside the directory that you want to add to the git repository needs to be added. The same applies to files that are part of the repository but that you have changed, for example in an editor. Adding files in git lingo only means that the changes done to the files are considered to be part of the repository, although at this point they are not yet part of the history. Adding files means that they are going to be part of your next commit, but except adding them to the list of candidates for the commit, nothing much happens when adding a file. You can make changes to files and then not add them -- which means they will not be committed. On the CLI you can type git add <FILENAME> or git add -A if you want to add all files. In GitHub Desktop new files in the directory are automatically added.
Once you have done a set of changes to your files and added them, you can save these changes to the git repository with git commit on the CLI. You will be asked to give a summary and a short description of the changes. In GitHub Desktop, you can enter a summary on the left bottom side of the window, add a short description, and then click the Commit to… button. After committing, the set of changes has become part of the local history. Each commit is identified by a unique hash.
Each time you commit files, they become part of the currently active branch. You can look at the history of commits to this branch by typing git log and you will see the hash for each commit along with who authored it, the date, and a description of changes. In the GitHub Desktop client you can see the history when you click on the History tab on the left pane in the GitHub Desktop client.
Most interactions with git like git add, git commit, or branching are done locally on your computer. If you want to interact with the shared project on GitHub, git pull gets the newest changes from the website and copies it to your local system. git push does it the other way: your local changes are sent to the webhoster. In the GitHub Desktop client this is easily done through the Fetch Origin button or through the menu Repository → Pull and Repository → Push.
Branches are basically different versions of a directory. By default, the standard branch in a project is called main. There is no limit on the number of branches, for example every developer can have a branch they are working on, or specific features can have their own branch during development. Branches branch off any other branch at a specific commit. Any branch can have any set of sub-branches. Following the feature branch workflow, the development of new code should always happen on a branch other than main. You can create a new branch called loeschef-feature-eyemap with git checkout -b loeschef-feature-eyemap or either by clicking on the arrow next to the Current branch or selecting Branch → New Branch from the menu in GitHub Desktop.
After a split, any of the branches can have any number of changes to the source code. The process of getting all these changes back together into a single branch is called merging. Following the feature branch workflow, we will use the Pull requests on the GitHub website for merging branches into the main branch. Once you think your code is ready for the main branch, push it to the GitHub website. Once it is there, you can select your branch and then click on the Contribute button and select Open pull request. The previous descriptions from your commits should already explain most of the changes, but you could summarize what you did in the title and description of the pull request. Then click on Create pull request. Someone else will then take care of the actual merge into main. By letting someone else do the merge, we automatically have a four eyes principle in place that will increase the code quality and reduce workload towards the end of the project.
