Moving to a feature-branch style of development

[bengineerdavis]

I'm running across an issue contributing to Bill's contributing to this project (his fork: https://github.com/billglover/django-concept). This to help complete issue #44 .

I've attempted to fork his fork, but realize that GitHub considers it part of the same repository (I think), and so even after renaming my current fork of the official CB repo, GitHub still won't let me fork Bill's fork of this repo (sorry for all the spamming of fork and repo!).

This made me realize that using a feature branch for things like our development setup and then sub-branches for docker-compose setups would make group contributions easier.

[lpatmo]

Can you say more about what you mean by using centralized feature branches? Would that require the maintainers to create a feature branch whenever there is a new feature that needs to be worked on?

---

In the case of "checking out" a PR from a fork (e.g. checking out https://github.com/billglover/django-concept), the way to do it is:

1/ git remote add bill https://github.com/billglover/django-concept.git
2/ git fetch bill
3/ git checkout bill/master
4/ Then you can git checkout -b a new local branch while you are there so that you can save any commits, push it up, and then create a PR on Blil’s repo.

References:
https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork
https://www.atlassian.com/git/tutorials/syncing/git-fetch

^ That second link explains steps 3 and 4 more clearly:

git checkout coworkers/feature_branch
Note: checking out coworkers/feature_branch'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b <new-branch-name>

[billglover]

Does feature-branching come with any overhead in terms of complexity for new contributors?

[brylie]

Feature branch flow is basically like saying "don't work in the master branch" and "keep your work focused on one feature". So, it can actually help new contributors to avoid problems like losing focus or having an out-of-sync master.

Working in a feature branch is basically the same as if they were to work in a fork of the project, which might be advisable for new contributors in any case.

[brylie]

For what it's worth, we have used Git Flow in a couple of projects, mainly to encourage the use of feature branches. There is a nice visual guide and helper script for Git Flow: https://danielkummer.github.io/git-flow-cheatsheet/

[bengineerdavis]

Thank you Brylie! Gitflow is exactly what I'm thinking of. I think it makes more sense to have an upstream branch for any fork that intends to provide PRs to the upstream. This would make it easier for other people to get involved because it would all be in the context of the Django CodeBuddies project. If we're constantly pushing to other people's forks to get a change into this code base, it could become a fairly messy affair to untangle down the road, when this is multiplied by a dozen or so forks that contain multiple upstream PRs, for example.

…

On Tue, Jan 28, 2020, 2:13 AM Brylie Christopher Oxley < ***@***.***> wrote: For what it's worth, we have used Git Flow in a couple of projects, mainly to encourage the use of feature branches. There is a nice visual guide and helper script for Git Flow: https://danielkummer.github.io/git-flow-cheatsheet/ — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#51>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMQU4TTVQGDOLLULOSCNQFLQ77LKFANCNFSM4KJMUQOQ> .

[billglover]

Consistent feedback I've had from development teams has been along the lines of "GitFlow is too complicated". A I'm not a professional developer myself so have never dug deeper.

I'm interested in:

• how it simplifies things for new developers
• how it simplifies things given the high "turnover" in active developers
• how it reduces the burden on core maintainers as more contributions come in

[brylie]

GitFlow is just providing a consistent way of doing things using common concepts. There are three main moving parts, which can be adopted à la carte:

• feature
• release
• hotfix

Features are just branches, which is already a common workflow. When you start working on a feature, you create a feature branch (from the development branch) to do your work in a sandboxed space.

Once the development branch is at the desired state, it is merged into the release branch (such as master). Releases are made from a release branch and use Git tags. This is also fairly common and tags are how GitHub manages releases.

Hotfixes are branches that are opened against the master branch in emergency cases where a significant bug has made it into production. It is not as common as the other two concepts (features and releases), so it might be adopted once the project matures.

[brylie]

I'm interested in:

how it simplifies things for new developers
how it simplifies things given the high "turnover" in active developers
how it reduces the burden on core maintainers as more contributions come in

The above questions could be asked about Git itself.

GitFlow is just a conventional Git workflow (hence the name). From what I can tell, GitFlow doesn't add too much ceremony or complexity compared to how many developers are already using Git.

[wuworkshop]

Hmm.. I feel like two different Git workflows are being conflated here. My understanding of the Git Feature Branch Workflow is more like this description from Atlassian:
https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow

Gitflow is described here:
https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

There's also Forking Workflow:
https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow

This post has some nice visuals of different Git workflows:
https://buddy.works/blog/5-types-of-git-workflows

[brylie]

Sure. The original request for using feature branches seems like a good suggestion. It is also worth noting, as is done in the Atlassian article, that Feature Branches and GitFlow are somewhat related.

[billglover]

I'm still trying to understand the article on GitFlow. Will have another read first thing tomorrow and see if I can work through how it might work.

There are some sections of the Forking Workflow that stand out from the Atlassian tutorial:

"The Forking Workflow helps a maintainer of a project open up the repository to contributions from any developer without having to manually manage authorization settings for each individual contributor."

"This also makes it an ideal workflow for open source projects."

"the Forking Workflow is commonly used in public open-source projects"

I get the feeling that these workflows all typically co-exist, the first distinction that we would want to make is: do we only accept contributions from members of the code buddies org, or do we accept contributions from those who aren't members, but have forked the project?

The second distinction appears to be, what branching patterns we want to adopt for contributions that occur within the organisation.

[brylie]

Here is a proposal, so we might be able to close this issue with some agreement:

1. use feature branches for developers working within this repository (as is the current approach)
2. allow users to choose their preferred branching style in forked repository pull requests
3. use Git tags for releases (default behavior for GitHub)

[bengineerdavis]

" Here is a proposal, so we might be able to close this issue with some agreement: 1. use feature branches for developers working within this repository (as is the current approach) 2. allow users to choose their preferred branching style in *forked* repository pull requests 3. use Git tags for releases (default behavior for GitHub)" #2 makes me a little nervous, especially if there's multiple people that might be coming in to comment--particularly core contributors. That spreads out the project in a way that feels like it would complicate management. How would we manage this?

…

On Wed, Jan 29, 2020 at 7:06 AM Brylie Christopher Oxley < ***@***.***> wrote: Here is a proposal, so we might be able to close this issue with some agreement: 1. use feature branches for developers working within this repository (as is the current approach) 2. allow users to choose their preferred branching style in *forked* repository pull requests 3. use Git tags for releases (default behavior for GitHub) — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#51>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMQU4TVMZPQ4XBPSIPUOS73RAFWK5ANCNFSM4KJMUQOQ> .

[brylie]

Idea number two was basically to acknowledge that people might fork the repository and experiment with the code. At some point, they might want to contribute code from their fork. GitHub is designed to allow this type of workflow and leaves it up to project maintainers whether or not they will accept the pull requests.

https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork

[lpatmo]

Catching up on this thread. :)

I think it makes more sense to have an upstream branch for any fork that intends to provide PRs to the upstream. This would make it easier for other people to get involved because it would all be in the context of the Django CodeBuddies project. If we're constantly pushing to other people's forks to get a
change into this code base, it could become a fairly messy affair to
untangle down the road, when this is multiplied by a dozen or so forks that
contain multiple upstream PRs, for example.

@bengineerdavis I understand what you're saying now! My counterpoint to this is I think Bill's docker PR was a bit of a special one where it was tempting to try to create PRs against his fork (to help with the work) because it was a major block of work. In general, though, PRs from shouldn't be so huge that they would necessitate new PRs on those forks.

For the past few months, I've been learning that the smaller the PR the better, because smaller PRs are easier to review -- but of course I haven't been very good at doing that in this project (yet).

Re: Gitflow

I took a look at https://danielkummer.github.io/git-flow-cheatsheet/ and I get the idea, but I do think it is more overhead than we want to introduce to new contributors, some of whom may be trying to get the hang of git itself first.

Here is a proposal, so we might be able to close this issue with some agreement:
1/ Use feature branches for developers working within this repository (as is the current approach)
2/ Allow users to choose their preferred branching style in forked repository pull requests
3/ Use Git tags for releases (default behavior for GitHub)

I like this! My only caveat to #2 is that I don't think we should admonish non-core contributors who for some reason or other forget to create a branch in their fork, but we should generally encourage creating branches as a good practice in our contributor documentation.

I'm imagining our contributor documentation saying something like:
1/ Fork the repository and git clone your repo
2/ git remote -v to double check your upstream and origin remotes are pointing to the right locations
3/ Create a new branch by typing git checkout -b [branchname]. If you're simply experimenting, feel free to name it anything. If you're working on a specific issue, please name it:

• git checkout -b feature/issue-X if it is a feature
• git checkout -b hotfix/issue-X if it is a hotfix

4/ git pull upstream master and git push origin master occasionally to make sure your branch is up to date with master. If you are working in a branch on your forked repo, remember to git rebase master after the two previous steps

On github.com/codebuddies/codebuddies, all new PRs were merged into staging, and a release happened whenever the staging branch was merged into master. I'm hoping to set up something similar here -- and will give releases tags too, of course.

(What do you all think of the flow above? Am I missing anything? Do folks prefer having an explicit release/0.0.1 branch as well?)

[billglover]

On the whole I agree with the proposal by @lpatmo.

Do we have an opportunity to simplify further by removing the need to distinguish between a hotfix and a feature. Maintaining the distinction implies we have two separate approaches for the fix, test, or deployment of hotfixes and features. I'm not sure we need this distinction.

[lpatmo]

I don't have a strong opinion either way, so decided to put this up in a Slack vote at https://codebuddies.slack.com/archives/C04BRN86J/p1580439065055600 so folks can vote if they have an opinion on either approach. :)

[billglover]

The poll on Slack has been open for a couple of weeks and is a dead heat.

The conversation under the poll tended towards concluding that issue-123-description would be a good branch naming strategy. As the proposed branch naming convention does not indicate any differentiation between feature and hotfix and I’m closing this issue.

There are still a number of open questions regarding the benefit of this proposed change and how it might be implemented, so would recommend we address these if we want re-open the proposal. Items raised in the Slack discussion include:

• What constitutes an issue vs a hotfix?
• If we were to distinguish, how would we treat them differently?
• What do we gain by making the distinction?
• Is the benefit worth the additional complexity?

[brylie]

There doesn't need to be much formality at this point.

We can just help new developers remember to create a branch when starting work, regardless of how they name it. Even if a developer accidentally commits to the master branch in their local fork, they can still create a branch and open a pull request from that branch.