How to follow this guide?#

I. First Time: When you first setup local development. You only have to do it once and it also contain useful knowledge on why this approach is better than any alternative.

II. Development Routine: What you normally do as a stand-alone developer. This should go in-hands with next section Collaboration.

III. Collaboration: Now it is not just you anymore. This section provides standard solution in resolving conflict of changes.

IV. FAQ: Frequently Asked Questions pointing to appropriate section and some advanced/detailed answers

I. First Time#

1. Fork the organisation’s repo onerch/OneRCH via the web interface

2. Clone your fork to local drive

3. Verify your local clone status and configured remote

Normally this would resulted in your remote being the source you cloned, i.e. <username> /OneRCH or onerch/OneRCH.

4. Add remote upstream from the organisation’s repo

git remote add upstream https://<username>@github.com/onerch/OneRCH.git

5. Fetch latest updates from the organisation’s repo

At this stage your history is not the latest, some people might pushed their changes to remote upstream.

git fetch upstream

II. Development Routine#

The very first thing before/after your development is to include any changes from upstream remote.

1. Apply updates to your local branch

git checkout --track origin/developing # For first time checkout
git fetch upstream
git checkout developing
git merge upstream/developing

2. Branching for development

Once updated any changes in the base branch to derive from for development, start checkout new feature branch from base branch.

git branch --verbose --all
git checkout -b feat-large-feature developing

3. Create Pull Request to merge to organisation’s branch

There are several methods to close a Pull Request:

• Create a merge commit

  • ✅ All commits included
  • ✅ Another merge commit

• Squash and Merge

  • ✅ All commits ‘squashed’ into one
  • ❌ Another merge commit

• Rebase and Merge

  • ✅ All commits included
  • ❌ Another merge commit

III. Collaboration#

Update your feature branch with latest changes#

What is this for?

• ✅ Confirm that your commits do not contain breaking changes
• ✅ Ensure you’re working on the latest version of development branch
• ✅ Help your teammates to keep track easily with a linear history

1. Similar to 1st step in II. Development Routine, sync base branch from upstream remote against your local base branch

2. Rebase changes from base branch onto your feature branch

git checkout feat-large-feature
git rebase developing

Cleanup your local commits history#

What is this for?

• ✅ Combine commits: forgot to refactor all variables, accidentally left out
• ✅ Keep the entire repository’s history as linear as possible

1. Check the SHA hash of the last commit you want to retain as-is, i.e. any commits made after this will be included in rebase
2. pick, squash or essentially drop commits
3. Re-write the commit message

git checkout feat-large-feature
git rebase -i <last-commit-retain-as-is-hash>

The rebase command also support relative (exclusive) distance from the commits pointed by HEAD. From previous example, making the third commit 35d9556 as the last-commit-to-retain-as-is with git rebase -i HEAD~3.

git checkout -b fix-small-typo feat-large-feature
git merge --squash fix-small-typo
git commit -m "Squash Commit Message Title"

Conflict & code breaking changes#

What is this for?

• ✅ Introduce featured implementation onto upstream
• ✅ Resolve redundant old version conflicts
• ✅ Adapt to the latest implementation from upstream
• ❌ Troubleshoot or Debug conflict changes

1. Fetch any updates from upstream
2. Try to merge to local base branch
3. Check status and open conflicted files to manually resolve it.

IV. FAQ#