[Discussion] Branching for 2.x and 3.0 releases

jessesquires commented 7 years ago

For 3.0 breaking changes like #397, we need to agree on a branching model.

We'll need to figure out how we want to manage two on-going releases (2.x and 3.0).

Branching

Suggestion:

Keep master "linear" and breaking, and have a release-2.x branch.
Master contains latest breaking changes, always
release-2.x is merged frequently into master to keep master ahead, always
When ready, release-2.x is merged into stable
GH/CocoaPods release cut from stable

I think this is probably best (though not optimal, IMO) since IG uses master. I went ahead and created the branch: https://github.com/Instagram/IGListKit/tree/release-2.x

The alternative (and more typical model) would be to do the opposite of this and maintain a release-3.0 branch, but that doesn't play well with IG working off of master.

Commits and PRs

We'll need to do one of two things for all pull requests and commits:

(1) If part of 2.x, make sure we merge to release-2.x. This can all happen via GH only. Then, we (admins) open a PR to merge release-2.x into master and sync FB internal.

OR

(2) We continue to merge into master only and then cherry pick appropriate commits into release-2.x.

Both of have their pros and cons. Either way, concerning our release process so far, we can't simply merge master into stable for releases.

jessesquires commented 7 years ago

cc @rnystrom @Sherlouk

Sherlouk commented 7 years ago

Agreed, master should be furthest ahead

Probably easiest to continue merging everything into master then cherry pick non-breaking commits into their own releasable candidate

Should probably update/write new guides to reflect any decisions made here

rnystrom commented 7 years ago

So workflow for release-2.x branch would be:

Someone adds a PR
If part of 2.x, PR is against release-2.x (nit: could we name it minor-release to use for 3.x?)
- Requires hitting "merge" PR button (consider #399)
To sync, create PR from release-2.x:master
- Use internal tools to land

Is that correct?

IMO the release process is already pretty manual, might as well cherry-pick. Only thing is the CHANGELOG.md would probably have to have 2 entries: one for next-major and one for next-minor. Right?

Sherlouk commented 7 years ago

I'd assume CHANGELOG.md would have 2.2.0 in the release-2.x branch and have 2.2.0 and 3.0.0 in master

jessesquires commented 7 years ago

Yeah, I guess we could just cherry pick into stable, and not have a 3rd "staging" branch.

This runs a great risk of conflicts though, and we'd likely get to a point where master and stable can never get back in-sync. (we'd have lots of stable-only conflict resolution, for example).

This is mostly cosmetic with regard to git history, but it will be maintenance burden.

Sherlouk commented 7 years ago

Regardless of the methodology you're going to have conflicts at one point or another

However assuming we keep master up-to-date with release-2.x, once we submit the next release stable and release-2.x will be the same and master will only be ahead with breaking commits.

We should never get to a point where there's a conflict going into stable meaning all conflict resolution will be tested on either release-2.x or master.

Assuming everything goes into master before being cherry-picked into release-2.x, conflicts will be resolved by PR author into master and you'd only need to deal with going intorelease-2.x. Though I don't see that being a massive issue often considering the only difference is breaking changes - and if a non-breaking change is interacting with a breaking change then they would both need to go in the same release anyway.

jessesquires commented 7 years ago

However assuming we keep master up-to-date with release-2.x, once we submit the next release stable and release-2.x will be the same and master will only be ahead with breaking commits.

Right, this is exactly what I want the end result to be.

... if a non-breaking change is interacting with a breaking change then they would both need to go in the same release anyway.

Ah, good point. 👍

Ok, I'm on-board with cherry picking into stable then.

We'll need to:

~~Updating contributing guidelines~~ (Nevermind, business as usual, merging to master)
Slightly change how we do the CHANGELOG, something like:

Changelog

3.0.0 (upcoming release)

... (on-going notes)

2.2.0

...

Since the CHANGELOG will be published continuously. However, how GH release notes will remain the same.

Sherlouk commented 7 years ago

@jessesquires Need to update the release checklist as well

Also as per @rnystrom's previous remarks, do we want to rename release-2.x? Suggestion was minor-release

rnystrom commented 7 years ago

It's probably ok to create a new branch per minor release now that we're just cherry-picking. We can just use the branch to collect commits, then merge that into stable, then close it. Cool?

jessesquires commented 7 years ago

@Sherlouk - Ah, well I think if we're cherry picking then we don't need that staging branch. We can stick with master and stable only.

jessesquires commented 7 years ago

That's simpler. In general, we just need to be very careful and diligent with managing releases.

Sherlouk commented 7 years ago

We'd still need a branch to store non-breaking commits? Unless you were planning to, only on release, go through all the commits and identify non-breaking ones

Feel like that opens the floor for human error, maybe if we do that we should add something to merge commit titles like "[breaking]" as to make it clear?

jessesquires commented 7 years ago

I think the process would be:

open PR
merge into master
if breaking, do nothing
if non-breaking, cherry-pick into stable

Also, before we merge any 3.0 PRs, we should merge master into stable so we have a clean start.

Sherlouk commented 7 years ago

While that process would work and probably be fine, I personally don't like the idea of stable being constantly pushed to.

I prefer the idea of having stable stable, and only updated when we decide to push a new tested version.

(Just my opinion)

jessesquires commented 7 years ago

Hm.. yeah.

Really, I'm not a fan of any of this setup. But we have to deal with FB's importing/syncing system.

Sherlouk commented 7 years ago

@jessesquires Do you mind filling me in on what Phabricator/FB internal sync offers?

Interested

Sherlouk commented 7 years ago

Either way I'm happy to go with what you think is best, if that's merging into stable immediately then so be it

rnystrom commented 7 years ago

@Sherlouk it let's us keep our internal repo the source of truth. Otherwise keeping 2 repos in sync will be a nightmare. We don't have any automation to make GH the source of truth and sync internally due to security concerns (pulling code/files into internal systems automatically = bad).

jessesquires commented 7 years ago

think we're good here?

Instagram / IGListKit