Git Branches

The OpenAPI Generator project works on multiple versions in parallel:

• upcoming patch release
• next minor release containing breaking changes with fallback
• next major release containing breaking changes with no fallback

Branches

To support several versions, several branches are used:

Status in June 2018:

• master branch is for upcoming patch releases (3.0.1, 3.0.2, 3.0.3, ...)
• 3.1.x branch for the next minor release
• 4.0.x branch for the next major release

Merge direction

To port changes from one branch to an other, the merge direction is always from the lowest version to the newer.

Example:

• Merge master branch into 3.1.0 branch
• Merge 3.1.0 branch into 4.0.0 branch

Those merge commits are done regularly by the core team.

Merge commit is kept in the history in order to facilitate merge conflict resolution.

Merging back on master

When we want to jump on the next version, the working branch is merged back:

Example (end of June 2018):

• When we drop the support for 3.0.x, we'll merge 3.1.x back into master:
  • There will be one last 3.0.x release : 3.0.3 (orange commit)
  • Then we merge 3.1.x into master, on the master branch the version is updated to 3.1.0-SNAPSHOT
  • The master branch is now use to do the next 3.1.0 release and then weekly bugfix releases: 3.1.1, 3.1.2 ...
  • We can create the 3.2.x branch to work on the next minor release 3.2.0-SNAPSHOT

How-to: create merge commits

Be careful of the merge direction. Keep merge commits as part of the history (no squash, ...).

Example for master -> 3.1.x branch:

git fetch
git checkout origin/3.1.x -B 3.1.x
git merge origin/master

Review the merge commit. You can run some checks locally mvn clean verify, bin/utils/ensure-up-to-date...

git push

Solving conflicts during merge

In the samples/ folder a lot of files contains the version of the generator .openapi-generator/VERSION, or comments in code:

Examples:

--- a/samples/____/.openapi-generator/VERSION
+++ b/samples/____/.openapi-generator/VERSION
@@ -1 +1 @@
-3.0.1-SNAPSHOT
\ No newline at end of file
+3.1.0-SNAPSHOT
\ No newline at end of file

or:

--- a/samples/client/petstore/php/OpenAPIClient-php/lib/Api/UserApi.php
+++ b/samples/client/petstore/php/OpenAPIClient-php/lib/Api/UserApi.php
@@ -17,7 +17,7 @@
  * OpenAPI spec version: 1.0.0
  * 
  * Generated by: https://openapi-generator.tech
- * OpenAPI Generator version: 3.1.0-SNAPSHOT
+ * OpenAPI Generator version: 3.0.3-SNAPSHOT
  */

Those conflicts can be ignored during merge (keep the "ours" version):

git checkout --ours samples/*
git add samples/*

Run mvn clean verify and bin/utils/ensure-up-to-date to be sure that you have updated the samples/ during the merge commit.

Necessary steps when a new working branch is created

• Working branch must follow the format 0.0.x (e.g. 4.3.x). This is required in .travis.yml
• Set it as protected branch in the GitHub configs
• Update readme (branch list, badges…)