Description of gitflow branches

[chrbertsch]

Open question: Shall we directly commit to master when fixing typos in the conversion from the release PDF version to the Asciidoc version for the standard or use a separate branch for that?
I propose to directly commit to master in that exceptional case.

[pmai]

I think most of those changes should go onto the newly created release/2.0.1 branch; where applicable the commits can be cherry-picked into develop (not master), if it seems reasonable that the change applies to 3.0.0-based stuff cleanly.

Rationale: The develop branch (and/or the feature branches branched off from develop that need to be merged back into develop) will diverge very rapidly from the current baseline (e.g. all prefixes change to fmi3, the whole document structure is likely to change if we add more introductury concept stuff, etc.). Changing master will likely lead to lots of merge conflicts later on in that case.

Which BTW seems to indicate to me that release/2.0.1 should not be merged back into master (and/or develop) later on (as would be customary under git flow): This again will just lead to lots of seeming merge conflicts, because 3.0.0 will completely supercede most 2.0.1 changes, for little gain.

I'd rather cherry-pick still-relevant changes from 2.0.1 onto develop, then merge develop as 3.0.0 back into master. 2.0.1, if it happens, might even be released after 3.0.0, depending on timelines, so I think merging both back into master is not going to work, and does not offer any real benefits (just tag 2.0.1 release from the release/2.0.1 branch and be done with it).

[pmai]

I've tagged @t-sommer as reviewer since I'd like his input on the whole 2.0.1 situation.

[t-sommer]

As I understand GitFlow the maintenance of old releases happens on support branches. IMHO it's also a good practice to prefix versions in tags and branches with "v" e.g. release/v2.0.1. Since 2.0.1 will likely never be merged back into master it should go into support/v2.0.x.

[t-sommer]

Shall we directly commit to master when fixing typos [...]?

No. I think we agreed that any contributions to the respective branches should be made via pull requests (this is not clearly stated in the docs). If it's only a typo we don't have to discuss it but at least it gets reviewed by another person.

[pmai]

Right, though they are not mentioned in most GitFlow docs, support branches are what make sense here. Though I guess the branch should be named support/2.0.x, since in theory multiple 2.0.x releases could be tagged from that. (While I previously also used various v2.x or version-2-x etc. conventions, I think the rule nowadays is to just use support/2.0.x since for those branches it is always clear that a version number is meant; see the examples you linked to).

[t-sommer]

I edited my previous comment as you suggested: support/v2.0.x

[t-sommer]

If we only have development, feature (FCP) and support branches we could use the following schema (I guess this is what you had in mind @pmai). Minor changes (typos etc.) could be handled via PRs.

master
  |
  +--->+ branch "v2.0.x"
  |    |
  |    + tag "v2.0.1"
  |    |
  |    + tag "v2.0.2"
  |
  +--->+ branch "v3.x"
  |    |
  |    + tag "v3.0"
  |    |
  |    +--->+ branch "v3.0.x"
  |    |    |
  |    |    + tag "v3.0.1"
  |    |    |
  |    |    + tag "v3.0.2"
  |    | 
  |    + tag "v3.1"
  |    |
  .    .
  .    .
  .    .

Every vertical line (|) could be a merged FCP branch or PR:

master
  |
  +<- merge PR "fix-typo-in-fmi-spec"
  |
  +--->+ branch "fcp06-arrays"
  |    |
  +<---+ merge "fcp06-arrays"
  |      

[t-sommer]

As for the "v" prefix: Semver use it for their tags. I would also suggest to rebase feature branches onto the latest master branch before merging them to make it easier for people to review changes in the standard.

[t-sommer]

I've put together a proposal for a branching and tagging schema that only uses feature and maintenance branches.

[chrbertsch]

Just to be sure, you propose not to follow Gitflow any more, right?

[t-sommer]

Yes, this would be a custom schema. I've considered it again and I think it suits our purpose better.

[pmai]

FWIW on the v Prefix semver seems to have reversed course: While semver 1.0.0 had the v prefix in its spec (and hence also uses it in their repo) that language was explicitly removed from semver 2.0.0...

[pmai]

On the proposal, I think this looks quite good, I‘d just urge to use prefixes like feature/ for feature branches, and maintenance/ or releng/ etc. for the maintenance branches since this really helps with command-line autocomplete and keeps everything tidier.

We’ll probably have more opportunity to discuss tomorrow... ;)

[t-sommer]

I've updated the proposal based on your suggestions and added some examples of what it would look like.

[t-sommer]

This has been clarified in d43c130