This is great.
One question - is it best practice to create branches in your own fork or on the master?
From a best practice perspective, It tends to makes more sense when the branch is done on someone’s fork as opposed to the main repo. It helps keep the branches clean on the main repo (you don’t have to scroll through a list of a bunch of stale branches that were never cleaned up and deleted). Typically master and release branches are done at the main repo level.
That being said, if you have a branch that you want a bunch of people to directly commit to (and not have to open PRs to contribute), it can make sense to put in a main repo.
The monome projects as far as I’ve seen follow the branch-from-personal-fork method for most contributions.
Unless you’re part of the team that owns a repo (or added as a collaborator) you can’t create branches in that repo.
In other words the default/normal workflow for non-team members is to create a fork and work from there.
If you want to create branches or not for work you do in your fork is your own choice of course
I’d suggest to use branches, makes it a bit easier to understand the history if looking at it via for example the command-line or with something like
tig or when looking a GitHub’s “network” graph (for example https://github.com/monome/norns/network).
Ok, great, then just checking does the command in these instructions
git checkout upstream/master -b name_of_your_branch
…create a new branch in the master or the fork?
git checkout -b newbranch will create a new branch in the repository you’re currently in. if it’s a fork it’ll create a branch in that fork.
this specific command implies it’s a fork, as it uses
upstream/master as the starting point. when you fork a repo you typically set up a remote named
upstream for the original repo (a remote named
origin will be automatically set up for your fork when you clone it).
OK, great, this is really helpful. Thank you.
I made a pull request for the
monome/dust repo. Here’s my workflow on a Norns and my computer.
- Fork repo into my personal account
- Clone fork onto my computer
- Create branch based on master for a new thing, named after new thing
- Add upstream as a new origin to stay in sync with master
- change the repo on the Norns to track my fork
- Push Changes to my fork as I’m working, Norns can stay in sync
- Edits made through Maiden (the Norns IDE) get diffs on device
When I got to a place where my fork + branch is ready, make a PR using Github’s interface. It assumes reasonable defaults and even displays a green button to make a PR.
I think it’s good etiquette to write pull requests with as much information as possible because reading diffs is a special skill. Describe the new features. Don’t describe anything not in the changes, even if the feature in mind is obvious. Future PRs can cover that.
update: another thing I forgot…delete branches when they are merged into
master. If you want to do a new thing, even if it’s for the same kind of thing, make a new branch with a new name about only that new thing.
I’m borrowing these conventions from my professional work as a software developer, though with niche software like Monome the rules are more flexible.
This might be useful to some: github released a training platform to learn how to use git/github.
Along with the other replies here, there is also the question of force pushing (a.k.a. history rewriting) and the surrounding etiquette.
While there are no hard and fast rules, I’ve found that in circumstances where a branch is seen as being your own private branch (that just so happens to be in public on GitHub) then force pushing is fine, and even required when tidying up work prior to a PR being accepted.
Whereas in branches that are seen as collaborative and public then force pushing is a no-no.
For most projects this usually means that branches on the main repo are never force pushed to, but that it’s okay to do it on your own forks.