New branch structure #435

Closed sgrossberndt closed 1 month ago

Current state

master
changes_for_v1.1
trip_monitoring example for a feature branch
typos-2023-11-07 example for a bugfix branch

changes_for_v1.1 is deployed to https://vdvde.github.io/OJP/index.html

Proposed strategy

based on GitLab Flow

Branches

main contains the most recent released state (former master)
develop contains the most recent agreed and merged development state (former changes_for_v1.1)
release/1.0 contains the most recent released state of the major version 1.0
release/2.0 contains the most recent released state of the major version 2.0
feature/trip_monitoring features are created as feature/* branches and merged into develop
bugfix/typos-2023-11-07 bugfixes are created as bugfix/* branches and merged into develop and, if necessary for a published release, into release/v2.0

Documentation

https://vdvde.github.io/OJP/index.html is a starting point file containing JavaScript which checks for subdirectories and creates links to them
https://vdvde.github.io/OJP/main/index.html contains the documentation rendered by the main branch, updated on merge/push to branch main
https://vdvde.github.io/OJP/develop/index.html contains the documentation rendered by the develop branch, updated on merge/push to branch develop
https://vdvde.github.io/OJP/feature/trip_monitoring/index.html contains the documentation rendered by the feature/trip_monitoring branch, updated on merge/push to branch feature/trip_monitoring
https://vdvde.github.io/OJP/release/v2.0.0/index.html contains the documentation rendered of tag v2.0.0, updated on create/published of release
https://vdvde.github.io/OJP/release/v2.0.1/index.html contains the documentation rendered of tag v2.0.1, updated on create/published of release

For pull requests I propose to only run checks, not deploy any documentation. This also makes sure that pull requests, which could be sent from anybody possibly with harmful content do not cause a deployed documentation on https://vdvde.github.io/

https://github.com/MicrosoftDocs/azure-devops-docs/blob/main/docs/repos/git/git-branching-guidance.md#manage-releases

@skinkie @ue71603 @herlitze

The default github-pages-upload action https://github.com/actions/deploy-pages we are using right now does not allow to specify an upload folder. This made the proposed documentation structure impossible or at least very hard to achieve, but switching to https://github.com/marketplace/actions/deploy-to-github-pages will make it easy as it allows to define an upload directory

Sounds fine with me. @skinkie what do you think?

I also had a look regarding getting changes_for_v.1.1 to main.

Up to version v1.0.1, which was also made a release at https://github.com/VDVde/OJP/releases things are fine.

A version v1.0.2 was tagged which solves some xmllint issues, but apparently not all of them as a v1.0.3 was released then, which not only added another fix "Fix schemaLocation towards siri_reference-v2.0.xsd (#211)" but also did several unfortunate additions to the master branch which make merging changes_for_v1.1 / 2.0 even more difficult, they also contain several problems:

d5550b9 add a travis integration that lints XML files with one space (I don't know why this was added to master at all in that state as Travis integration was already done in changes_for_v1.1 back then)
a39103a add a commit "Proposal for a TripStatusGroup" which should only have been added to v1.1. It was added to changes_for_v1.1 later then and there were changes to the pull request before even which renamed the element "Unable" to "Infeasible" as discussed here which is a conflict now. As discussed here I implemented the proposed "option A" back then by rewriting commit history, but apparently this has been overwritten in the meantime..
2c5d18b add a Travis CI update commit which should have been squash-merged

Usually one would want to have a complete succession of commits for all releases, but in this case I'd like to do it differently: All additions to master after v1.0.1 are either already part of changes_for_v1.1 or not necessary for it. Merging changes_for_v1.1. into master leads to merge conflicts which are difficult to resolve. In order to make things easier I would like to ignore all additions to the master branch after v1.0.1: the current master branch becomes releases/1.0, main starts at v1.0.1 and changes_for_v1.1 becomes develop.

I just hope that the generation of the documentation can be 'stacked'. My understandig is that the generation happens once the pull request comes in, not after it is merged.

As I wrote in https://github.com/VDVde/OJP/issues/435#issuecomment-1805879263 I am sure stacking is possible when switching from the default github-pages-upload action to https://github.com/marketplace/actions/deploy-to-github-pages

You are correct that my proposal is missing the documentation for the feature/bugfix branches, I will update the proposal accordingly.

I just updated the proposal.

Sounds good to me.

bugfixes are added to main too? I think yes.
release x.0 branches. Will there be x.x branches too? or would 1.0.1 be in the 1.0 branch. Should we label them as releases anyhow? I think only x.x and certainly not x.x.x so we could have a release/1.1, but we would not have a release 1.1.1 or do you prefer to have them.
About the merging. I can agree that we do base release/2.0 on 1.0.1. But will release/1.0 still be 1.0.3 (which I would prefer).

@sgrossberndt thank you for your thoughts on this and the explanation! I approve your suggestion.

@ue71603

bugfixes are added to main too? I think yes.

Yes, once they are part of a released version for the latest major version

* release x.0 branches. Will there be x.x branches too? or would 1.0.1 be in the 1.0 branch. Should we label them as releases anyhow? I think only x.x and certainly not x.x.x so we could have a release/1.1, but we would not have a release 1.1.1 or do you prefer to have them.

This depends on how granular later releases may happen. Would we release a 1.0.99 after having released a 1.1.0? If yes, it could make sense. But it would not be mandatory to have them.

* About the merging. I can agree that we do base release/2.0 on 1.0.1. But will release/1.0 still be 1.0.3 (which I would prefer).

Yes, that was apparently ambiguous: I only want to base release/2.0 on v1.0.1, release/1.0 is based on v1.0.3.

VDVde / OJP