[Processes] Publication process for new versions

[marwin89]

What?

We need a proper publication process for new versions within GitHub.

Suggestion: Do a branch-based approach.

1. Development of the specification could be done in a development branch.
2. Multiple changes can be aggregated (and potentially reverted) in the dev branch.
3. The changes in development branch are not considered "published" yet.
4. When we want to publish a new revision of a version we can merge the development branch into main, thereby making the changes official.
5. If we want to have different publication schedules for different versions of the spec we could use more than one dev branch.

Why?

Manage publications of new versions properly, efficient and secure
for Instance

1. Introduction of a change that should be reverted shortly afterwards
2. Aggregation of multiple (editorial) changes to keep the revision history short
3. Planning of publications for a certain point in time.

More Information

This has been touched on in #66.
Suggestion comes from @codello

[marwin89]

@codello I would definitely do a branched based approach for publication process. It's better than the situation right now. @Baklap4 do you agree?

I could create a dev branch in an instant. As a start I'd keep it simple just using one dev branch for the next version 2.0.0:
development/v2.0.0

[Baklap4]

Hmm personally i don't think we'd need a branched approach

Yes main-branch would hold the published version
Everything we want to publish can be just a pr and be discussed within it.
In the end after a PR is done it should be considered final in my honest opinion. If it is not considered final or things are still open for discussion it should not be merged since apparently stuff is not clear for everyone yet.

Introduction of a change that should be reverted shortly afterwards

I don't think this project is that dynamic / changed often to have a usecase for this.

Aggregation of multiple (editorial) changes to keep the revision history short

This would be nice but can also be achieved by PR management as we've done since start of project

Planning of publications for a certain point in time.

Can also be achieved by PR management like we already do

If we want a sort of staged approach you could opt for a 2nd branch -> development (disregarding the versionnumber)
Where every pr would be merged into. Then at some point in time we will merge this into main therefor updating the published version. But personally i'd skip this since it requires more labor with barely any benefit opposed to just keep the discussion in the PR and merge it once its final and well thought out. 9/10 times people using a dev branch all the changes on dev will go towards main without any second thought rendering it pretty much useless

Also a s a note: Now we keep a changelog - revision log per version. This can be summarized within a changelog with a section dedicated to each version.

[marwin89]

@Baklap4 okay good arguments!

Then we have 3 options now:

1. ❤ Introduce branched based approach, Multiple development branches for each version
2. 🚀 Introduce branched based approach, but just one development branch without versions (Compromise)
3. 🎉 No branched based approach, publications just via PRs

@codello what do you think? Are you convinced?

[codello]

I agree with @Baklap4 that a branch per version is probably too much overhead. I see some arguments in favor of a separate branch:

• The ability to revert changes: I agree that this project is not that dynamic and that everything can and should be discussed in PRs. However, the amount of discussion that does happen is also not that high. I feel like there's a risk that a PR might not be reviewed carefully enough.
• The ability to keep the revision history concise: With a single main branch we would have to add to the revision history with each change. I think this is not a huge issue but to me it feels more elegant to batch up multiple changes into a single revision history entry. I think that makes the revision history more useful and digestible.
• It would be easier to create PRs. If a PR does not update all versions of the file format that it should or does not include a revision history, it can be amended by a second PR. This is of course also solvable by a good PR review process.

There's some challenges with a separate branch:

• If we publish a new revision of a version of the file format we would have to publish all versions simultaneously. We can't just publish a revision for v1 and not publish staged changes for v2 (or rather we could not merge the branch but would have to cherry-pick). I don't think this is necessarily a problem, just something to keep in mind.
• It is not immediately clear to me how we would handle changes for the Website. I don't think the website should necessarily follow the same publication process as the specification file. On solution could be to maintain the website in an unrelated/orphaned branch.

I'm personally unsure where I currently stand. A major pain point for me with a directly-to-main approach is that maintaining the revision history becomes more difficult.

[codello]

I did already start to create a contribution guide for this project last month in which I also thought of a dev-branch approach with a separate website branch. I have created a draft PR #86 how that could look like. Of course this issue will be decisive whether that's actually the way we want to proceed, I just thought it might be a helpful reference.

[marwin89]

Results

Dear all, @Baklap4, @codello , there's only few participation in this voting after 5 weeks. I close voting.

Decision is 4 against 3.

Result: Keep everything in one main branch

Please re-open if needed.

---

@codello could you adjust your PR #86 accordingly?