Skip to content

Guide: Github Workflow

Jump to bottom
knod edited this page Jul 17, 2019 · 2 revisions

Github Workflow

Table of Contents

What's the Point?

I've found this really helps me keep things clean and untangled when collaborating. A side benefit is that there are less merges, so less noise in the commits of the main branch. It looks long and complicated, but I've found it pretty simple and fast when actually doing it. I'm also open to any ideas for improvement, either in the flow itself, or in the description here.

TL;DR For The Advanced Reader

The shortest explanation possible

Never change the 'dev' branch in any way other than pulling in upstream. Do everything in new branches, deleting those branches as they get accepted.

Slightly Longer Short Version

First make an upstream remote to this repo. We'll call it 'cfb' here.

  1. git checkout dev
  2. git pull cfb dev
  3. If contributing a new feature/improvement:
    1. git checkout -b new-branch
    2. Make changes then add and commit them.
    3. git push -u origin new-branch the first time, git push thereafter
    4. Rinse and repeat 3.2 and 3.3 as you wish.
    5. When ready, go to Github and make a PR to whatever cfb branch is appropriate (usually 'dev').
    6. By the way, if you want to work on other files, do steps #1 to #3.4 over again with a different branch name. Don't touch this 'new-branch' unless you specifically want to change the PR.
    7. Wait till your PR is accepted or rejected, then
    8. git branch -d new-branch
    9. git push origin :new-branch or, for git >= v1.7.0, git push origin --delete new-branch.
  4. If continuing work on and old feature/change branch:
    1. git checkout old-branch
    2. Update this branch too with git pull cfb dev.
    3. AS LONG AS YOU HAVEN'T MADE A PR YET, if your git status has now diverged from origin even though you were synced up before, just git push --force
    4. Got to step 3.2 and do all that.

You Talkin' To Me?

This lower section is written with less experienced git'ers in mind, so it will say not to do certain things and will exclude some unnecessary options. If you feel especially confident about something, feel free to use your judgement.

Assumptions

This assumes that you know:

  • How to use your terminal/command line
  • How to fork a Github repo
  • How to clone that forked Github repo onto your local machine and then interact with that clone
  • What a branch is
  • What a remote repo is
  • What your origin remote is
  • What adding your changes is about
  • What commiting your changes is about
  • What pushing to a remote branch is about
  • How to make a pull request through Github

If you don't know those things, feel free to message one of us and we can help get you where you need to be. Alternatively, you can google around for a while. There are a lot of resources out there about git. In future, we'll try to add some useful resources and tutorials to this page.

Don't Panic

Whatever happens, whatever you do, even if you end up burning down the entire original cliff-effects repo, others of us have solid copies. We can nuke whatever's remaining and make it shiny again, and we can help others do the same. There are warnings about stuff below that are in bold to get your attention, but, really, it's all fixable one way or another.

Set up

  1. Fork this repo.
  2. Clone it.
  3. DON'T OVERWIRTE YOUR LINK TO origin, but do:
  4. Add a link-up to another remote repo with git remote add a-useful-name cliff-effects-github-repo-url. For 'a-useful-name' I've often used upstream, but other possible options are code-for-boston or c-f-b or cliff-effects. We're going to call it 'cfb' from now on. Remember that you'll have to type it in a lot. Official people explaining it: https://help.github.com/articles/adding-a-remote/
  5. Do git remote -v to make sure that you've properly created that link.

Step 0: Still Concerned?

If you're worried about messing up, one absolutely surefire way to make sure that nothing gets too tangled is to make a copy of the local folder, open that location up in terminal, and do your experiments there. If this is where you're at make sure you don't do anything involving push until you feel solid. Then when you're ready for the real deal, go back to your actual project folder and do it for real. If you forgot you were working in the duplicate and did a bunch of stuff you don't want to redo, don't worry about it. You can throw out the old 'actual project folder' and just work out of the duplicate from now on.

Step 1: Sync Up

  1. Start from the dev branch with git checkout dev.
  2. Do git pull cfb dev.
  3. Do this pretty often to keep up with other changes that get made.

Step 2: Work on a New Feature/Improvement

  1. Check out a new branch with git checkout -b a-branch-name. It doesn't matter what the branch name is, but try to use a name that makes sense. It can make it easier for us and you to, at a glance, understand your intentions.
  2. Make your changes.
  3. push your changes
  4. Repeat the last two until you're ready to make a pull request through github.
  5. Make a pull request through github.
  6. If you get suggestions for changes:
    1. Make those changes.
    2. git push again. This will change your PR. NOTE: Unless you do want to make changes to your pull request, don't touch this branch anymore, it's made of lava.
  7. Otherwise/in the meantime:
    1. VERY IMPORTANT: Go back to the 'dev' branch with git checkout dev
    2. Feel free to check out new branches to work on anything that doesn't need the changes you just made.

Step 3: Sync Up and Make Other Changes

  1. Do Steps 1 and 2 again however much you want.

Step 4: Your PR Is Merged

  1. Do step 1 to update your 'dev' branch
  2. Delete your old branch EVEN IF YOU'RE GOING TO BE WORKING ON THE SAME FEATURE THAT THE BRANCH WAS FOR. If you want to keep working on the feature, you'll be able to make a new branch with the same exact name in just a moment.
    1. Delete the local copy with git branch -d a-branch-name
    2. Delete the remote branch either
      • through github
      • or from your terminal with git push origin --delete a-branch-name or, if you have an older version of git, git push -u origin :a-branch-name
  3. Make a new branch with whatever name you want, even the same name: git checkout -b a-branch-name. It's clean and fresh as new fallen snow and you can do whatever you want with it. Your 'origin' branch is the same - it's like it never existed.
  4. Carry on from Step 2, item 2.
  5. Rinse and repeat.

Now you won't have to worry about remembering to update a branch or about diverging with 'origin'.

Something went wrong

If something goes wrong, there may be people working on the project who can help. @knod and others have some experience. There's also ohshitgit.com.

Clone this wiki locally