Contribution workflow

[nmalky]

We need to have a discussion about our "standard" workflow, to be referenced in the volunteer docs.

From the perspective of a new volunteer, I've put in some of the things I've learned in the "How to contribute code" guide. See: https://github.com/sourcebots/volunteer-docs/pull/5

To start off:

• How should branches/forks be used? When is it worth creating a branch on the original repo (requires permission to be an organisation member) vs just forking?
• How should issues be used? When to create them? When to assign people? What our labels mean, and how to use them.

A link to a good guide (or guides) with some organisation-specific adjustments would be useful here. e.g. https://guides.github.com/introduction/flow/ ?

[PeterJCLaw]

• How should branches/forks be used? When is it worth creating a branch on the original repo (requires permission to be an organisation member) vs just forking?

The following is general to the majority of projects I've seen on GitHub as well as a description of my understanding of how SourceBots works.

Branches

All work is done on feature specific branches. Since for us (and pretty much all GitHub based projects) the "unit of work" somewhat ends up being a pull-request, we should keep the small and focussed to a specific topic. Note that this is different to projects where the "unit of work" is a commit. The Linux kernel is an example of the latter, where they'll iterate specific commits until the series is ready to apply.

As a result of us working by pull-request, we expect that fixes (for example from code review) will simply be added to the branch rather than injected in-between or as part of existing commits. This is because adjusting the history (for example via rebasing) messes with how GitHub presents comments on the pull-request.

Forking

"Forking" is arguably the wrong word here (bad GitHub), since the "forks" on GitHub usually aren't divergent, but are instead clones for development in.

As far as general usage goes, there is no meaningful different between a pull-request within a repo and one between repos. Both are completely supported scenarios (as long as you used the GitHub "Fork" button to create the repo you want the changes to be pulled from) and can be used interchangeably. Both result in the PR appearing in the list of PRs on the target repo and both end up being administered by the maintainers of the target repo.

The only difference is that, within a fork, the original author has complete control over the branch while in a branch on the original repo the branch may be subject to restrictions from that repo. Example restrictions include not being able to push non-fast-forward commits to it, or requiring that users must be a member of the organisation to be able to push changes.

We seem currently to prefer to be working in a single repo with branches (rather than forks with branches).

Opinion

I think we should move away from single-repo and towards contributors having forks. This is a very common pattern on GitHub and is how most projects work. Typically the core contributors would have access to the main repo, though even then it's often the case that they'll work in their own "forks" before emitting pull requests.

By keeping the development branches out of the core repo, we get the following:

• the workflow works as well for new people as well as core contributors, ensuring a low barrier-to-entry This is important as new people might not have push access yet, and/or maybe haven't even met us yet, but want to fix something; SR had competitors occasionally submitting fixes in this manner.
• freedom to experiment with things which are very half-baked, without worrying about them being in the main repo; https://github.com/sourcebots/robot-api/pull/78 is an example of this, as (sort-of) is https://github.com/sourcebots/sb-vision/pull/22 and my related experimental branchs (though the benefit from keeping that one out of the repo is more about repo size from adding lots of large binary files)

[PeterJCLaw]

How should issues be used? When to create them?

I currently use issues for "here's a specific thing which needs fixing in this repo", which I see as separate from Trello since Trello is more "here's a general task or outcome we want"

When to assign people?

I'm not sure. I've never used assignment. I wasn't sure from GitHub's emails what you'd meant by using it here, though I think using it for gathering comments is reasonable. I think GitHub's expectation is that people use it to denote who will be working on something.

What our labels mean, and how to use them.

With the exception of "work-in-progress", all the labels here are the defaults. Hopefully all the (current) labels are sufficiently self-explanatory?

I don't think we should document things which are self-evident, such as that the "work-in-progress" label is for stuff which is being worked on and isn't ready for review. Similarly if we do start actually using labels, then the presence of them should be sufficient documentation that they should be used.

[PeterJCLaw]

Having read https://guides.github.com/introduction/flow/, I think that does a pretty good job of describing how we work.

[RealOrangeOne]

When to assign people?

My opinion on this is to assign people when a ticket has explicltly been given to a person to do. If youre opening an issue, then assigning it is unnecessary, unless you know it's an issue only they can fix. If assigning to a PR rather than an issue, then perhaps using this as an edit lock is a good workflow (IE I created this PR, but i'm handing work over to X for a bit), but I often just don't do this, as it never really comes up.

If you need a PR / issue to be seen by someone, or it requires their input, then tagging and posting in the related slack room is a good alternative. If it's just useful input, and there's no rush, just leave it, most people are watching the repos they care about, and will see it eventually!