Discussion: Version Branches

[lance]

Currently the repository is tagged for each prerelease, mirroring the spec versions as they progressed. However, there are no release branches. This was probably fine prior to 1.0. But now that 1.0 is out, a v1.x branch should be created and maintained so that fixes can be backported to previous versions as we continue to move forward with changes in the repository.

I suggest the following:

• Create a v1.x branch off of the v1.0.0 tag.
• Create a v1.x-backport label which can be used to label any PRs that have landed since the 1.0.0 release, indicating they should be considered for backporting to the v1.x branch.
• As appropriate, create patch releases off of the v1.x branch, tagging the repo on the v1.x branch with v1.0.1, for example, for the next patch release.
• As appropriate, create minor releases off of the v1.x branch, tagging the repo on the v1.x branch with v1.1.0, for example, for the next minor release.
• If needed create a v1.1.x branch for minor release patch updates.
• As appropriate, create patch releases off of the v1.1.x branch, tagging that branch with v1.1.1, for example, for the next patch release in this major/minor combination.
• Repeat for 2.0.0 and up on their own branches.

This is related to the question raised in #72 where the contributor's guide talks about using the develop branch. That hasn't been done since the 1.0.0 release. We need to decide if we want to move forward with this process. If so, then the develop branch needs to be updated with all recent commits, and set as the primary branch in the repository settings. This setting will ensure that by default, pull requests from contributors are created to land on the develop branch.

My personal feeling is that the develop branch is mostly redundant with master and we don't really need to do that. If contributors can manage rebasing their pull requests with updates from master regularly, this shouldn't be a problem. Though I think this does add some pressure to land PRs quickly. What are other's thoughts on this?

[fabiojose]

@lance I am with you lets remove the develop and works with master. As you said, no activity landed to develop for a long time, then it useless to maintain this branch.

[lance]

@fabiojose great - I'll leave time for others to comment and will start a PR with some docs around this (or whatever is eventually agreed on in this discussion).

[grant]

This is a really long issue, so I'm sorry if I'm misunderstanding something.

I'm in favor of removing develop and working with master.

I don't think we should create branches for releases, just tags and releases at a tag. This is how the Go SDK and requires much less work. Having multiple branches is a pain.

Branches suggest that there will be future patches on these branches.

[grant]

A separate concern is that the version of this npm module shouldn't be tied to the CloudEvent spec support version. I'm not sure if that's clear, but it's worth restating. The interface for using CloudEvents may change over time even with the same specversion.

mirroring the spec versions

This may have been done in the past but it can't continue. Otherwise, the client (SDK) will be stuck in making non-breaking changes.

It's common to use different version client/SDKs than the CE spec itself.

[lance]

@grant yes I agree - versioning of the module is independent of spec version.

Regarding version branches... yes, this assumes that improvements will be made on release versions. I think it's reasonable to assume that the 1.0.0 version of this module will be updated to 1.1.0 or 1.0.1 after version 2.0.0 is out. Release branches help simplify this.

The go SDK seems to follow this pattern: https://github.com/cloudevents/sdk-go/tree/release-1.y.z

That branch seems to be analogous to my proposed v1.x branch, but also integrates my proposed v1.1.x. I'll concede that the patch level branch in my proposal is overkill. But I think it's still important to have the major version branch - how's this?

• Create a v1.x.y branch off of the v1.0.0 tag.
• Create a v1.x.y-backport label which can be used to label any PRs that have landed since the 1.0.0 release, indicating they should be considered for backporting to the v1.x.y branch.
• As appropriate, create patch releases off of the v1.x.y branch, tagging the repo on the v1.x.y branch with v1.0.1, for example, for the next patch release.
• As appropriate, create minor releases off of the v1.x.y branch, tagging the repo on the v1.x.y branch with v1.1.0, for example, for the next minor release.
• Repeat for 2.0.0 and up on their own branches.

[grant]

@lance OK, that sounds fine, although a lot of work right now. I'll let you lead that.

Are we unblocked for removing 0.3 support with #99 or is there something else we need to decide before I can create a PR?

[lance]

@grant Let's just slow down a tiny bit so that we can ensure everyone agrees on a process, it can be documented, branches can be created, we can ensure CI is set up properly to test these branches, etc. I don't think there's a huge rush to land a naming change right now. Let's do it right.

[grant]

I don't quite understand the proposal above. If you want to create extra branches at this point that are separate from master, then that's fine with me. Seems like a lot of work that won't be very useful to users right now.

---

With ensuring everyone agrees on the process, can you be more specific? Who do you want to agree? @fabiojose already said he was OK with removing 0.3, not sure about this branch aspect. Who else?

[lance]

I don't quite understand the proposal above.

What don't you understand? It's a proposal for managing branches and versions of this module as we move forward.

Sure I can just create a branch and go to town, but I would like to have agreement on this overall strategy first. In what way is creating a branching strategy based on versions a lot of work? And why do you think it will not be useful? I think having clarity on how versions are managed is incredibly useful.

Really doesn't seem like a lot of work to agree on something and have consistency. I'm sorry that you seem to be dissuaded by that.

[grant]

I'd rather have:

• 1 master branch with the current state of the code
  • New features can use a branch for their respective PRs like we've been doing
• N number of GitHub releases when we are in a stable state https://github.com/cloudevents/sdk-javascript/releases
  • We can refer to previous releases there.

I don't want to have to patch previous versions that will never get into master. I don't want to have any backports. I don't understand why we want to create so many branches when we can use releases instead.

[grant]

I'd rather have:

• 1 master branch with the current state of the code

  • New features can use a branch for their respective PRs like we've been doing

• N number of GitHub releases when we are in a stable state https://github.com/cloudevents/sdk-javascript/releases

  • We can refer to previous releases there.

I don't want to have to patch previous versions that will never get into master. I don't want to have any backports. I don't understand why we want to create so many branches when we can use releases instead.

I think this understanding is a bit old. So long as we don't have an unmanageable level of branches and eventually stop support for old branches, that's fine.