New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doxygen: Add release workflow documentation #326

Merged
merged 1 commit into from Sep 17, 2018

Conversation

Projects
None yet
3 participants
@ubruhin
Member

ubruhin commented Sep 9, 2018

Our first release should be ready soon, so we need a strategy how to create and maintain official releases :) See #188.

This is my idea for a release workflow. Any thoughts about it?

Rendered: https://doxygen.librepcb.org/_branches/add-release-workflow-documentation/da/dbc/doc_release_workflow.html

@dbrgn

This comment has been minimized.

Show comment
Hide comment
@dbrgn

dbrgn Sep 11, 2018

Contributor

Looks good generally.

If I understand this correctly, then after releasing version 2.0.0, the master branch is immediately considered to be version 3.0.0, right? This would mean that if 90% of the features don't affect the file format, 90% of the features would need to be cherry-picked or merged to the release branch, for version 2.0.1, 2.1.0, etc. That seems like a lot of effort (especially considering that after the file format has stabilized, maybe a year or more can pass before the next major version is released).

Contributor

dbrgn commented Sep 11, 2018

Looks good generally.

If I understand this correctly, then after releasing version 2.0.0, the master branch is immediately considered to be version 3.0.0, right? This would mean that if 90% of the features don't affect the file format, 90% of the features would need to be cherry-picked or merged to the release branch, for version 2.0.1, 2.1.0, etc. That seems like a lot of effort (especially considering that after the file format has stabilized, maybe a year or more can pass before the next major version is released).

Show outdated Hide outdated dev/doxygen/pages/release_workflow.md Outdated
Show resolved Hide resolved dev/doxygen/pages/release_workflow.md
Show resolved Hide resolved dev/doxygen/pages/release_workflow.md
Show outdated Hide outdated dev/doxygen/pages/release_workflow.md Outdated
Show resolved Hide resolved dev/doxygen/pages/release_workflow.md
Show resolved Hide resolved dev/doxygen/pages/release_workflow.md
@ubruhin

This comment has been minimized.

Show comment
Hide comment
@ubruhin

ubruhin Sep 11, 2018

Member

If I understand this correctly, then after releasing version 2.0.0, the master branch is immediately considered to be version 3.0.0, right? This would mean that if 90% of the features don't affect the file format, 90% of the features would need to be cherry-picked or merged to the release branch, for version 2.0.1, 2.1.0, etc. That seems like a lot of effort (especially considering that after the file format has stabilized, maybe a year or more can pass before the next major version is released).

Correct. To avoid that, we could prepare releases directly on master (all the commits which I've drawn on the release branch would be on master then), and tags are created directly on master. Then the release branch and increment to the next major version could be done just before a file format change is needed. Such changes could even be hold back to stay on master as long as possible.

Overall this may require less effort because cherry-picking could be replaced by fast-forward merges, but I think it requires much more discipline on the master branch (on every commit on master you must be sure that it doesn't affect the file format) and also leads to a confusing Git history (sometimes release branches are equal to master, sometimes not; sometimes the file format on master is stable, sometimes not).

Because of that, I would rather go with cherry-picking. Or do you have a better idea?

Member

ubruhin commented Sep 11, 2018

If I understand this correctly, then after releasing version 2.0.0, the master branch is immediately considered to be version 3.0.0, right? This would mean that if 90% of the features don't affect the file format, 90% of the features would need to be cherry-picked or merged to the release branch, for version 2.0.1, 2.1.0, etc. That seems like a lot of effort (especially considering that after the file format has stabilized, maybe a year or more can pass before the next major version is released).

Correct. To avoid that, we could prepare releases directly on master (all the commits which I've drawn on the release branch would be on master then), and tags are created directly on master. Then the release branch and increment to the next major version could be done just before a file format change is needed. Such changes could even be hold back to stay on master as long as possible.

Overall this may require less effort because cherry-picking could be replaced by fast-forward merges, but I think it requires much more discipline on the master branch (on every commit on master you must be sure that it doesn't affect the file format) and also leads to a confusing Git history (sometimes release branches are equal to master, sometimes not; sometimes the file format on master is stable, sometimes not).

Because of that, I would rather go with cherry-picking. Or do you have a better idea?

@rnestler

This comment has been minimized.

Show comment
Hide comment
@rnestler

rnestler Sep 11, 2018

Member

So for example as soon as the version "0.2.0" is released, the version "0.1.x" is no longer maintained.

So lets see if I get this right: We maintain the "0.1" branch as long as we are developing "0.2" on master. And all non file format breaking changes will actually be cherry picked to the 0.1 branch.
As soon as 0.2 is released we will stop maintaining 0.1 and start 0.3 development on master.

So does it even make sense to have the release branches then? The only time I can see value in it is if we have breaking changes in the 0.2/master branch and later on non-breaking changes which do not depend on the previous breaking changes which can be cherry-picked to 0.1.
Otherwise I could see a strategy where we develop 0.1.0 then 0.1.1 on master and as soon as we have a breaking change start naming master 0.2 and then just cherry pick small bugfixes into the 0.1 branch.

Edit: Ah I missed the comment by @ubruhin above, which discusses almost exactly this.

Member

rnestler commented Sep 11, 2018

So for example as soon as the version "0.2.0" is released, the version "0.1.x" is no longer maintained.

So lets see if I get this right: We maintain the "0.1" branch as long as we are developing "0.2" on master. And all non file format breaking changes will actually be cherry picked to the 0.1 branch.
As soon as 0.2 is released we will stop maintaining 0.1 and start 0.3 development on master.

So does it even make sense to have the release branches then? The only time I can see value in it is if we have breaking changes in the 0.2/master branch and later on non-breaking changes which do not depend on the previous breaking changes which can be cherry-picked to 0.1.
Otherwise I could see a strategy where we develop 0.1.0 then 0.1.1 on master and as soon as we have a breaking change start naming master 0.2 and then just cherry pick small bugfixes into the 0.1 branch.

Edit: Ah I missed the comment by @ubruhin above, which discusses almost exactly this.

@rnestler

This comment has been minimized.

Show comment
Hide comment
@rnestler

rnestler Sep 11, 2018

Member

Overall this may require less effort because cherry-picking could be replaced by fast-forward merges, but I think it requires much more discipline on the master branch (on every commit on master you must be sure that it doesn't affect the file format) and also leads to a confusing Git history (sometimes release branches are equal to master, sometimes not; sometimes the file format on master is stable, sometimes not).

Yeah I think this is exactly the trade off: The linear development on master is simpler and less maintenance burden, but requires some developer discipline in regard to file format breaking.

Member

rnestler commented Sep 11, 2018

Overall this may require less effort because cherry-picking could be replaced by fast-forward merges, but I think it requires much more discipline on the master branch (on every commit on master you must be sure that it doesn't affect the file format) and also leads to a confusing Git history (sometimes release branches are equal to master, sometimes not; sometimes the file format on master is stable, sometimes not).

Yeah I think this is exactly the trade off: The linear development on master is simpler and less maintenance burden, but requires some developer discipline in regard to file format breaking.

@ubruhin

This comment has been minimized.

Show comment
Hide comment
@ubruhin

ubruhin Sep 11, 2018

Member

So lets see if I get this right

Yes, you got it right :)

And all non file format breaking changes will actually be cherry picked to the 0.1 branch.

I wouldn't say all, but only the most useful ones, and only if the next major release is not yet in sight. So generally I think we should always be focused on the next major release instead of maintaining already released versions. Who cares if between 1.0.0, 2.0.0, 3.0.0 etc. are no (or very few) other releases :)

The linear development on master is simpler and less maintenance burden, but requires some developer discipline in regard to file format breaking.

What I forgot to mention: In addition to discipline, it also needs to stop accepting new (even non-breaking) features while we are in release phase. For example after releasing v1.0.0-rc1 (directly on master), we must not accept anything else than bugfixes until v1.0.0 is released. Who knows how many release candidates need to be created and how long it takes until the final release. Release branches allow to stabilize releases (only cherry-picking bugfixes) while development continues on master as usual.

Member

ubruhin commented Sep 11, 2018

So lets see if I get this right

Yes, you got it right :)

And all non file format breaking changes will actually be cherry picked to the 0.1 branch.

I wouldn't say all, but only the most useful ones, and only if the next major release is not yet in sight. So generally I think we should always be focused on the next major release instead of maintaining already released versions. Who cares if between 1.0.0, 2.0.0, 3.0.0 etc. are no (or very few) other releases :)

The linear development on master is simpler and less maintenance burden, but requires some developer discipline in regard to file format breaking.

What I forgot to mention: In addition to discipline, it also needs to stop accepting new (even non-breaking) features while we are in release phase. For example after releasing v1.0.0-rc1 (directly on master), we must not accept anything else than bugfixes until v1.0.0 is released. Who knows how many release candidates need to be created and how long it takes until the final release. Release branches allow to stabilize releases (only cherry-picking bugfixes) while development continues on master as usual.

@dbrgn

This comment has been minimized.

Show comment
Hide comment
@dbrgn

dbrgn Sep 11, 2018

Contributor

Who cares if between 1.0.0, 2.0.0, 3.0.0 etc. are no (or very few) other releases :)

It should be as easy as possible to create new releases, because it will mean new features and fixes will reach users faster 🙂

we must not accept anything else than bugfixes until v1.0.0 is released

But pull requests can already be filed and discussed.

Alternatively, you could also create a next branch with only breaking changes that will eventually be merged into master before the next release. Basically an inverted cherry-picking workflow, where most features go onto master, and breaking changes go onto next.

Contributor

dbrgn commented Sep 11, 2018

Who cares if between 1.0.0, 2.0.0, 3.0.0 etc. are no (or very few) other releases :)

It should be as easy as possible to create new releases, because it will mean new features and fixes will reach users faster 🙂

we must not accept anything else than bugfixes until v1.0.0 is released

But pull requests can already be filed and discussed.

Alternatively, you could also create a next branch with only breaking changes that will eventually be merged into master before the next release. Basically an inverted cherry-picking workflow, where most features go onto master, and breaking changes go onto next.

@ubruhin

This comment has been minimized.

Show comment
Hide comment
@ubruhin

ubruhin Sep 12, 2018

Member

It should be as easy as possible to create new releases, because it will mean new features and fixes will reach users faster

For me it's more important to make releases as stable as possible, not publishing them as early as possible. And stabilizing releases is much easier on separate release branches than on master.

But pull requests can already be filed and discussed.

And after weeks or months I have to ask contributors to rebase their branches (even if they were ready much sooner), which is annoying for contributors. I prefer that the pain of release management is on my side, not on contributors side ;) Also you couldn't implement feature B which depends on A as long as A is not merged.

Alternatively, you could also create a next branch with only breaking changes that will eventually be merged into master before the next release. Basically an inverted cherry-picking workflow, where most features go onto master, and breaking changes go onto next.

And what would we have won? Then the pain is to merge next into master because this would be done only once a year or so. So the pain is just moved to somewhere else ;) In addition, one would have to choose the target branch of a PR depending on whether the PR changes the file format or not. That's annoying for contributors, and also GitHub doesn't allow to change the target branch afterwards so probably we would have to close and re-open PRs many times...

I think release management is a pain anyway, we can only choose where the pain is:

  • Either the continuous development is a pain (discipline on master, hold back PRs in release phase, next branch, ...)
  • Or maintaining older releases is a pain (cherry-picking)

In my opinion the latter option is much better for contributors (because they don't have to worry about release management at all) and leads to faster and easier development.

Member

ubruhin commented Sep 12, 2018

It should be as easy as possible to create new releases, because it will mean new features and fixes will reach users faster

For me it's more important to make releases as stable as possible, not publishing them as early as possible. And stabilizing releases is much easier on separate release branches than on master.

But pull requests can already be filed and discussed.

And after weeks or months I have to ask contributors to rebase their branches (even if they were ready much sooner), which is annoying for contributors. I prefer that the pain of release management is on my side, not on contributors side ;) Also you couldn't implement feature B which depends on A as long as A is not merged.

Alternatively, you could also create a next branch with only breaking changes that will eventually be merged into master before the next release. Basically an inverted cherry-picking workflow, where most features go onto master, and breaking changes go onto next.

And what would we have won? Then the pain is to merge next into master because this would be done only once a year or so. So the pain is just moved to somewhere else ;) In addition, one would have to choose the target branch of a PR depending on whether the PR changes the file format or not. That's annoying for contributors, and also GitHub doesn't allow to change the target branch afterwards so probably we would have to close and re-open PRs many times...

I think release management is a pain anyway, we can only choose where the pain is:

  • Either the continuous development is a pain (discipline on master, hold back PRs in release phase, next branch, ...)
  • Or maintaining older releases is a pain (cherry-picking)

In my opinion the latter option is much better for contributors (because they don't have to worry about release management at all) and leads to faster and easier development.

@dbrgn

This comment has been minimized.

Show comment
Hide comment
@dbrgn

dbrgn Sep 12, 2018

Contributor

GitHub doesn't allow to change the target branch afterwards

That's not true anymore, since 1-2 years 🙂

But I think I agree about the release branches.

Contributor

dbrgn commented Sep 12, 2018

GitHub doesn't allow to change the target branch afterwards

That's not true anymore, since 1-2 years 🙂

But I think I agree about the release branches.

@ubruhin

This comment has been minimized.

Show comment
Hide comment
@ubruhin

ubruhin Sep 12, 2018

Member

That's not true anymore, since 1-2 years slightly_smiling_face

Ah, good to know :)

Member

ubruhin commented Sep 12, 2018

That's not true anymore, since 1-2 years slightly_smiling_face

Ah, good to know :)

@ubruhin ubruhin merged commit 29955b6 into master Sep 17, 2018

4 checks passed

continuous-integration/appveyor/branch AppVeyor build succeeded
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

@ubruhin ubruhin deleted the add-release-workflow-documentation branch Sep 17, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment