Git

In a perfect world, we'd like this repository to be as close to Yelp/love as we can make it. That makes it easy for us to share changes we make, so that Yelp and others can benefit from them. It also makes it easy for us to benefit from upstream changes by Yelp.

Unfortunately, this is not a perfect world, and so we can't actually share a master branch, because we do need to maintain some differences from Yelp/love. Our master branches are already diverging for at least the following changes:

• Some UI changes like links, which I thought would be useful for users of CWRU love.
• Some backend changes that have to do with how user importing works.
• Some YAML changes (e.g. departments.yaml, version numbers, etc).

As a result, contributing is not an easy story. Any branch that is based on Yelp/love@master will bring in a lot of extra commits from Yelp's history if we merge it directly into hacsoc/love@master. Any branch based on hacsoc/love@master will cause the same problems for Yelp/love. So, before you do any development, you need to decide ahead of time whether you think your contribution would be useful upstream, or if you think it is specific to CWRU Love.

Recommended Repository Setup

You ought to have two remotes (three if you don't have push access to hacsoc/love)

• origin pointing to your fork, if you don't have push access to hacsoc/love
  • if you do have push access to hacsoc/love, that will be origin, and replace hacsoc with origin in further instructions
• hacsoc pointing to [email protected]:hacsoc/love.git
• yelp pointing to [email protected]:Yelp/love.git

All git commands in this article will assume you have this setup.

Local-Only Changes

If you're certain your change should only affect CWRU Love and has nothing to add upstream, then base it on hacsoc/love@master. All changes should have a PR, and should be approved by a member with write access. You can approve your own PR if you have write access and it's urgent, but generally don't do this. It's better to have multiple sets of eyes on the code.

$ git fetch --all
$ git checkout -b your-feature-branch hacsoc/master
# development ...
$ git push -u origin your-feature-branch
# do PR

Note that if you have push access, you can push to hacsoc instead of origin.

We prefer the "rebase and merge" style, because it eliminates merge commits and frequently makes the history more linear and logical (since master is constantly fast-forwarded).

Upstream Changes

For changes which might go upstream, the process is a bit more involved. You want to base your branch on Yelp/love@master, and make your changes there. Once the PR is accepted upstream, we'll add it to our fork as well.

$ git fetch --all
$ git checkout -b your-feature-branch yelp/master
# development
$ git push -u origin your-feature-branch
# do PR (upstream)

Again, note that you can push to hacsoc if you have access.

Once the PR is accepted, this only gets your changes merged into upstream. From there we need to get them into our own repo. Keep reading for instructions on how to do that.

Adding Changes from Upstream

If upstream has new features (contributed by Yelp, us, or others) that we want, we have to "cherry-pick" the commits onto our own branch. Even when adding upstream changes, PRs are still required (although you can condense them into one PR if the change represents several upstream PRs that were all merged).

$ git fetch --all
$ git checkout -b your-feature-branch hacsoc/master
$ git cherry-pick SHA  # do this for each commit (excluding merge commits) we want
$ git push -u origin your-feature-branch
# do PR

Again, you can push to hacsoc if you have access.

It's possible (although not likely right now) that the commit will conflict, since we do differ a bit from upstream. If that's the case, and you're confident that you know the differences and resolve it yourself, feel free to do so. Otherwise, you can escape the conflict with git cherry-pick --abort and (nicely) ask somebody (like Stephen) to do it for you.

Keep Up With Upstream

To avoid conflicts, it's important to keep the differences between forks minimal. That means we ought to quickly cherry-pick things as they hit upstream master, even if they don't seem critical to function. You can always see the diff between forks like this:

$ git fetch --all
$ git diff yelp/master hacsoc/master

If there are any differences that don't need to be there, then by all means submit a PR to eliminate the difference! Staying close is key to benefiting from Yelp's continued development, as well as contributing our own improvements.