default branch discussion: develop vs master

[tyleryasaka]

We've gone back and forth on this, but I am creating this issue because our current setup is confusing for new contributors.

For example, see the thread on this PR: #121

EDIT: I'm not proposing we change anything right now, necessarily. I'm hoping this can just be an ongoing discussion and that we can collect everyone's thoughts here.

[joshfraser]

I think a lot of the confusion could be fixed with a better getting started guide for contributors that breaks down how we do things here at Origin.

I'd vote for using the #contributing section of our docs for new contributors orientation. That way we have a single place to update the information and we can just link people there from each of our repos, Discord, etc.

[jessieay]

Better docs would help, but better defaults would be even better, IMO. If PRs will always be against develop, then setting it as the default branch would be a helpful default for new and old contributors alike.

As far as I can tell, it is only a designation that sets a default for when people open PRs: https://help.github.com/articles/setting-the-default-branch/

It is totally possible that there are good reasons to keep master as the default that I am unaware of.

[joshfraser]

It's also the default branch that people see when they visit Github. We actually had develop as the default for a while, but ended up changing it back. There's a pretty strong convention around using master as the default branch. Like @tyleryasaka said the develop branch is often broken & we want new folks to have a stable branch to play around with. Our thinking is that once you've decided to contribute, then you can switch over to the bleeding edge version.

[DanielVF]

(We seldom actually break develop - the tests still pass, and things work. However any two origin repo's develop branches may not be in sync with each other, and thus cloning the current develop for each project has good odds of getting you a broken local system)

[nick]

My 2 cents is that we should move to using 'master' for both origin-js and demo-dapp. If demo-dapp depends on changes in origin-js then we should only merge the pull request once the corresponding change has been merged to origin-js (ie do both at the same time). We should also ensure the master branch is never in a broken state

[dobbs]

I'm a newcomer to your project, but not a new developer. Maybe still too early to settle a develop vs master question.

In older projects, the tagged releases on github are the safe place to go for stable versions and cloning master is signing up for the full developer's experience, if you ask me.

I expect to trip over details like this as I get acquainted with a new-to-me project. And more so for a project that's pretty new.

Whether the unpaved roads are named master or develop seems worth figuring out, but not today. 😃

[gaboesquivel]

Also newcomer here! Github has a standard collaboration flow called Github flow, that's what most open source projects use. I would strongly suggest sticking to it, the current workflow seems more like GitFlow that is rarely used in open source.

I've recently posted an article with some tips for enhancing the github flow, things and tricks I've learned along the way.

https://gaboesquivel.com/blog/2018/15-recommendations-to-enhance-your-github-flow/

Github Flow https://guides.github.com/introduction/flow/
Conventional Commits https://conventionalcommits.org/

[gaboesquivel]

using hub.github.com this is how the workflow looks like. All from the command line!

git clone git@github.com:OriginProtocol/origin-js.git
cd origin-js
git fork
git checkout -b my-feat-branch
touch one.js
git add one.js
git commit -m 'feat: add one feature'
git pull --rebase origin master  ( reapply your commits on top of lastest master )
 - OR - 
git pull origin master ( merge master on top your work )
git push gaboesquivel my-feat-branch   ( push the branch to your fork )
git pull-request

notice that with hub you don't use the conventional upstream remote name, you use origin instead.

The pull request reviewer can download the PR code for testing using

git checkout https://github.com/OriginProtocol/origin-js/pull/1

Then on the Github UI click the button Squash Merge and make sure the commit msg is good enough to meet standards.

[dobbs]

Now that I've taken the time to read both links from @gaboesquivel #123 (comment), both suggestions seem like very sensible, and pretty light-weight suggestions that would make life easier in the long run.

There's only one rule: anything in the master branch is always deployable.

Maybe coordinating releases between demo-dapp and origin-js would boil down to this:

1. release changes to origin-js first.
2. demo-dapp depends only on released versions of origin-js

Devs, working on features in demo-dapp that depend on changes in origin-js would have to bundle their not-yet-released origin-js.

It implies the deploy of changes to origin-js needs to be frequent enough to reduce risk of log jams or code conflicts in changes to demo-dapp.

[nick]

I like this process too and agree that Squash Merge should be the preferred way to merge. I noticed Facebook uses squashed commits when merging changes to react. It makes for a tidier commit history.

[micahalcorn]

Considering this done per OriginProtocol/origin-devops#16 ☑️

[micahalcorn]

In an effort to enforce the decision made here, I've disabled merge commits and rebase merging on the monorepo. This may not be ideal for rare cases when we are merging a feature branch into another feature branch. If necessary, I can reverse this setting on-demand or permanently. Thanks to @tomlinton for the suggestion. cc @franckc @wanderingstan

[hohwille]

Just a side-note: IMHO git-flow with master branch is flawed by design. It never worked if you do maintenance releases after having a major release out. Hence, building releases via an artificial master branch is an anti-pattern that should be discouraged. With feature based development and PRs there is no need for this at all.
I might be biased, just my personal oppinion with 15+ years of professional SCM experience...

[micahalcorn]

Thanks for stopping by @hohwille 👍