Code Collaboration#

This section describes the use of Git and Github in relation to standard Tudat developer use cases. This chapter does not serve as a complete tutorial on Git, but rather as common practices with fundamentals of the Git workflow (or Gitflow) used by a Tudat Developer.

Note

Git comes with the Anaconda and Miniconda distributions by default. If you are using Conda, then Git is already available in your Conda command-line interface (specific to your OS).

Audience

Prerequisite(s)

Time

Git Beginner

git - the simple guide

~ 10 minutes

Learning Objectives

  1. Understand the differences between Git and Github.

  2. Clone and manage repositories from Github.

  3. Understand the Tudat Git workflow.

  4. Make your first contribution to Tudat.

Cloning a Repository#

Cloning a repository is a straightforward process. Each repository on GitHub has a green Code button. After clicking this button, you can then choose to “Clone with HTTPS” by clicking the clipboard icon under the dropdown and executing:

git clone <repository_url>

The primary version of the repository source code will be cloned.

Note

The master branch has commonly served as this primary version of a repository, though Github has changed this default to main in recent times in an effort to align with political correctness. master and main will be used interchangeably in this document, where images or repositories have not been updated.

Todo

Update all graphics, documentation and repositories to the new default main.

Try it yourself!

After entering your desired directory with the cd command, clone the developer-primer repository [1]:

$ git clone https://github.com/tudat-team/developer-primer.git

You now have a local repository set to the main branch of the remote developer-primer repository 🎉

developer-primer
├── .authors
│   ├── AUTHORS
│   ├── .authors.yml
│   └── .mailmap
├── bibtex.bib
├── CHANGELOG.rst
├── docs
│   ├── build
│   ├── make.bat
│   ├── Makefile
│   └── source
├── environment.yaml
├── .gitignore
├── LICENSE
├── news
│   └── TEMPLATE.rst
├── README.rst
├── rever.xsh
└── source
    └── tree_trunk.txt

There’s a lot going on in the Repository structure, don’t be overwhelmed. By the end of the Primer, you will have all the knowledge required to navigate it like a pro Tudat Developer.

Develop and Master Branches#

Instead of a single master branch, this workflow uses two branches to record the history of the project. The master branch stores the official release history, and the develop branch serves as an integration branch for features. It’s also convenient to tag all commits in the master branch with a version number. [2]

The first step is to complement the default master with a develop branch. A simple way to do this is for one developer to create an empty develop branch locally and push it to the server (remote):

git branch develop
git push -u origin develop

Note

The -u flag simply tells Git to track the newly created remote branch.

This branch will contain the complete history of the project, whereas master will contain an abridged version. Other developers should now clone the central repository and create a tracking branch for develop. If you form part of this group, (i.e. a develop branch already exists on the remote) you can create a tracking branch for develop by executing:

git checkout --track origin/develop

A tracking branch simply means that you have a local version of a branch that is connected to an existing remote version. This relationship is invaluable as it provides two major benefits:

  1. Pushing and pulling becomes a lot easier.

    • git push origin develop replaced by shorthand git push

    • git pull origin develop replaced by shorthand git pull

  2. Git will now inform you about “unpushed” and “unpulled” commits.

Try it yourself!

With the developer-primer repository [1] cloned, check what branches exist on the remote:

$ git branch -r
origin/HEAD -> origin/main
origin/develop
origin/main

You can think of the HEAD as the “current branch”. The output above shows that there there is indeed a develop branch available on the remote. Let’s create a local tracking branch:

$ git checkout --track origin/develop
Branch 'develop' set up to track remote branch 'develop' from 'origin'.
Switched to a new branch 'develop'

Congratulations, you are now on your local version of the develop branch, which is tracking the remote version of develop 🎉

Feature Branches#

Each new feature should reside in its own branch, which can be pushed to the central repository for backup/collaboration. But, instead of branching off of master, feature branches use develop as their parent branch. When a feature is complete, it gets merged back into develop. Features should never interact directly with master. [2]

Note

Note that feature branches combined with the develop branch is, for all intents and purposes, the Feature Branch Workflow. But, the Gitflow Workflow doesn’t stop there. Feature branches are generally created off to the latest develop branch.

Creating a feature branch#

Continue your work and use Git as demonstrated beforehand.

Try it yourself!

With the developer-primer repository [1], ensure that the develop branch is checked out, and create a new local feature branch with your Github username as the feature name.

$ git checkout develop
Already on 'develop'
Your branch is up to date with 'origin/develop'.
$ git checkout -b feature/ggarrett13_was_here
Switched to a new branch 'feature/ggarrett13_was_here'

After creating a feature that is appropriate for the planned work, carry out the work! Just for sake of example in modifying the source of a project, carve “<your_github_name> was here!” to the tree trunk contained in the source directory, using the command:

Note

This is just some arbitrary example “work” of modifying a projects source code for sake of example, not a convention or standard.

$ echo "ggarrett13 was here!" >> source/tree_trunk.txt

Your message will be appended to the bottom of the tree_trunk.txt:

source/tree_trunk.txt#
----- This is a tree trunk -----
ggarrett13 was here!

Stage source/tree_trunk.txt to be committed:

$ git add source/tree_trunk.txt

Finally, commit the changes made to your feature branch:

$ git commit -m "ggarrett13 was here!"
[feature/ggarrett13_was_here 6810969] ggarrett13 was here!
 1 file changed, 1 insertion(+)

You’re all set to leave your first mark on the Tudat Space community.

Finishing a feature branch#

When you’re done with the development work on the feature, the next step is to merge the feature/name into develop.

$ git checkout develop
$ git merge feature/name

Try it yourself!

Continuing with the developer-primer repository [1], checkout the develop branch in your local repository and merge your feature into it.

$ git checkout develop
Switched to branch 'develop'
Your branch is up to date with 'origin/develop'.
$ git merge feature/ggarrett13_was_here
Updating e2285f3..6810969
Fast-forward
 source/tree_trunk.txt | 1 +
 1 file changed, 1 insertion(+)

Finally, push the changes to the remote:

$ git push
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 364 bytes | 364.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To https://github.com/tudat-team/developer-primer.git
   e2285f3..6810969  develop -> develop

Congratulations, you’ve just officially made your first mark on the Tudat Space community as a Tudat Developer! 🎉

Release Branches#

Todo

Complete Release Branches section. Currently not a common part of the Tudat Developer workflow, but will be soon!

Hotfix Branches#

Todo

Complete Hotfix Branches section. Currently not a common part of the Tudat Developer workflow, but will be soon!

Chapter Summary

Gitflow Workflow [2]

  1. A develop branch is created from master

  2. A release branch is created from develop

  3. Feature branches are created from develop

  4. When a feature is complete it is merged into the develop branch

  5. When the release branch is done it is merged into develop and master

  6. If an issue in master is detected a hotfix branch is created from master

  7. Once the hotfix is complete it is merged to both develop and master