Skip to content

Latest commit

 

History

History
93 lines (60 loc) · 4.65 KB

contributing.md

File metadata and controls

93 lines (60 loc) · 4.65 KB

Contributing

Commits

https://www.conventionalcommits.org/en/v1.0.0/

Commits are linted via using commitlint

Setup

Required

In an effort to keep PR's clean, we use rebase/squash git workflow.

Please read up on what rebasing is if you are unfamiliar. The tl;dr is that rather than merging two linked lists (git merge) and creating a new merge commit, we're cutting and pasting (git rebase) from one branch onto another. The rest of the guide will assume a basic understanding of git rebase.

Please run the following commands

git remote add upstream [email protected]:c2c-project/prytaneum.git # You may need to setup ssh keys
git fetch upstream

NOTE: You may use a name other than upstream. However, upstream will be assumed throughout this guide.

Optional

git config --global core.editor "code --wait" # RECOMMENDED set vim as the preferred text editor instead of vim, you may also need to install the gitlens extension on vscode
git config --global pull.rebase true # pull will now fetch+rebase instead of fetch+merge

I want to open a PR into dev

Step 1. Fetch upstream

git fetch upstream

Step 2. Rebase

git rebase -i  upstream/dev

Step 2a. What commits do I keep

You should keep any new commits and drop everything else, usually (also drop any merge commits if there are any). If you see a commit that you know was merged in a different PR that is yours, drop it. The commit shows up because we use a squash/rebase workflow. Meaning that commit has probably been squashed into another, different, commit.

Step 2b. Resolving conflicts

Rebasing onto upstream/dev will re-run your commits on top of the new upstream/dev HEAD (cutting and pasting your commits on top of upstream/dev). This may result in some conflicts.

You probably made your modifications iteratively. If you have 10 commits, and there's a merge conflict in commit 1, you will only see your work up to commit 1. Resolve the merge conflict with respect to how commit 1 should look if you had started on the latest upstream/dev. As you continue to rebase, you will see more and more of your completed work.

Step 3. Pushing to your forked branch

When you push to your forked branch you'll probably have to force push. That's okay since only you are working on that branch. You'll need to do this every time you rebase.

FAQ

  1. What is rebasing?
    This will probably answer most of your questions

    Here is a useful video that can also be referenced.

  2. Why rebase instead of merging?
    Honestly, it's just preference. Rebasing in interactive mode forces you to make sure your changes are merged correctly commit-by-commit instead of all at one time in a git merge (the default strategy in a git pull). Pro-tip: you can change the default behavior of git pull to rebase: git config --global pull.rebase true. If you don't want to change it for all of your projects with git, just remove the --global flag.

    If you're interested to hear more of an explanation, ask in slack.

  3. Is there something wrong with merging?
    Nope. This is all just preference. There is a tradeoff with rebasing: rebasing changes history. When you're rebasing, any changes you make or conflicts you resolve is actively changing the history. If you're rebasing a public branch, this can be problematic. If you're the only one editing said branch, then it's not really an issue to git push --force, however, this should always be done with caution. If you google "git rebase vs merge" you'll find lots of passionate discussion :)

  4. I have a merge commit, is that bad?
    Not at all. We'll still merge the PR, just make sure the diff isn't something outrageous.

  5. I think something is wrong in this guide. That's certainly possible! Open a PR or send a message with what you believe is wrong/the fix.