Outreach student sharing a git repo

Sharing a GitHub fork

If you are planning to work on an issue with one or more members of your class, you will need to think carefully about a workflow for "out of tree" joint development.

Single developer workflow

For a single developer, the workflow is easy:

Single developer workflow initial setup

Click "fork" the main Kata Containers - repository to create your own copy or "fork" of the main Kata Containers repository.

Clone the main repository:

$ git clone https://github.com/kata-containers/kata-containers

Change into the clone directory:
```
$ cd kata-containers
```
Add a git "remote" for your fork:

Note: A git "remote" is simply a name / reference / alias / shortcut way of specifying the URL of your fork on GitHub.

In general terms:
```
$ git remote add "$some_name" "https://github.com/${github_user}/kata-containers"
```
A more concrete example:
```
$ git remote add james-github https://github.com/jodh-intel/kata-containers
```
Notes:
- This assumes your GitHub username is jodh-intel. It won't be so change that.
- This assumes you are called James. Obviously change it if that is not your name ;)
- Once you've created the remote, you can refer to your fork in all git commands as james-github rather than having to specify the full https://github.com/jodh-intel/kata-containers URL.

Single developer development workflow

Change files
git commit -as -m "A commit message"
git push -f "$your_remote"

Multi developer workflow

Sharing a git repository between multiple developers is a little awkward. There are various approaches but the recommended approach is simply for all developers to always git pull to ensure their local copy of the code is up-to-date, then git commit and git push back to the shared fork. Over time, a potentially large number of commits will build up. This is fine as the final stage will be to squash them into a single one just before raising a PR.

The crucial rule is that none of the developers sharing the fork should run git rebase as that will invalidate the existing history and make git pull fail for the other developers.

Initial setup

All developers first need to follow the single developer workflow initial setup to create their own fork and add a remote for it.
Decide on which developers fork will be the "main" one.

The main fork will act like the main Kata Containers repository for the group of developers working on a feature collaboratively.
Once you've decided on a "main" fork, all developers apart from the owner of the fork need to add a remote to the main fork. For example:
```
$ git remote add some-cool-feature-repo "https://github.com/${main_github_user}/kata-containers"
```

Multi developer development workflow

git checkout the-feature-branch
ESSENTIAL: Download commits pushed by colleagues:
```
$ git pull
```
Make your own changes:
```
$ git commit -asm "..."
$ git push
```

When you want to raise a PR

When the branch is working well and you are comfortable with the code, you will need to squash all the commits created by you and your colleagues into a single commit before raising a PR.

It is important to communicate with your team before you do this because squashing the commits will mean that they can no longer git pull without errors (since git has recreated the history).

Once you've all decided to stop shared development and raise the PR:

# Download the latest official commits from the main repo
$ git checkout main
$ git pull

# Ensure you have all the commits from your colleagues
$ git checkout the-feature-branch
$ git pull

# Squash the commits into a single one
$ git rebase -i main

Keep pick for the first (top) commit in the editor.
Change all the other pick prefixes to squash.
Save and quit the editor.
If the rebase was successful, run it again to reword the (single) commit message to ensure it complies with the required patch format.
Once you've edited the commit message, again save and quit the editor.
Push your changes back to your fork:
```
$ git push -f
```
Note: The -f is required to force update the fork as the rebase has changed the git history.
Browse to main Kata Containers - repository and click the yellow banner that should be displayed asking if you want to create a PR.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly