Use of branches

This document describes how we manipulate branches in our repository.

What branches do we use

develop

Various PRs are created for Agile data and accepted into develop branch once in a while. There might be one or few PRs per week. All PRs are "squished" before merging into 'develop' branch. Rarely there are some direct commits into 'develop' that will primarily fix broken builds or implement hot-fixes. (commits)[https://github.com/atk4/data/commits/develop]

master

From time to time, we review develop branch and if we are happy with it, we create a new release, which is merged into master branch. Those releases are tagged (e.g. 0.4.1 and are considered "stable". Using composer's version "*" is just like using master branch.

experimental

There is also experemental branch which can merge various PRs before they are actually reviewed.

This branch may be deleted and re-created, so if you run into conflicts fast-forwarding it, just delete and fetch it again.

History in 'experimental' branch will contain various un-squished merges.

legacy version branches

While software is in early development, version tags for releases start with 0 (0.3, 0.4, etc). Once we achieve stability, we will maintain major / minor releases through dedicated branches (1.0, 1.1, 1.2 etc)

Sample Release Timeline and branch use

• 1.0.0 released from develop and merged into master.

• 1.0.1 released from develop and merged into master (minor API change). Details are posted in CHANGELOG.md

• 1.0.2 released from develop and merged into master (bugfix)

• 1.1.0 released from develop and merged into master (major API change). Details are posted in CHANGELOG.md

• 1.1.1 released from develop and merged into master (bugfix)

• 1.1.2 released from develop and merged into master (urgent security fix)

• branch 1.0 created from 1.0.2 and an urgent security fix is cherry-picked

• 1.0.3 released from 1.0 (for legacy users)

• 1.2.0 released from develop and merged into master (major API change). Details are posted in CHANGELOG.md

• 1.2.1 released from develop and merged into master (urgent security fix)

• branch 1.1 created from 1.1.2 and an urgent security fix is cherry-picked

• 1.1.3 released from 1.1 (for legacy users)

• update 1.0 with cherry-pick of urgent security fix

• 1.0.4 released from 1.0 (for legacy users)

• 1.2.2 released from develop and merged into master (minor API change). Details are posted in CHANGELOG.md

• the new repository created for 2.0 by forking this repository.

Which version / branch to use

Agile Data Developer

If you are an active developer who contributes to Agile Data on a daily basis, you should create 'feature/my-branch' with the code that you currently work on.

You can occasionally merge 'develop' branch into your feature branch, then create PR for review by others. At least one other developer must review PR before they are merged. Always use 'develop' as destination branch.

You can also push into other people feature branches.

Contributor

Fork Agile Data repo under yourname/data and submit PR through GitHub. You do not need any extra permissions to do that. Follow Github forking guide.

Manually override repository for atk4/data in composer if you have to. Alternatively, you can symlink vendor/atk4/data to your development folder. Composer is smart enough not to trash your work.

Typo fixing

Use Github's "edit" button on files, that will simplify PR creation for you.

User of bleeding edge branch

Use dev-experemental inside your composer to get some of the recent features. You can also use dev-feature/blah-blah if you need a specific PR inside your project. You may, however, get a broken code ocassionally.

User of development version

Use 'dev-develop' inside your composer. This is updated pretty often and the code quality will always be good.

User of latest stable verison

Use version '*' or master branch while your project is in active development. This way you can get the most recent verison of Agile Data inside your project.

Code freezing your project

If you're code-freezing your project you should switch to '^1.2.4' version. Use the most recent one and this format will ensure that you still get the updates (security fixes) but you will avoid any major API change.

Super-stable-code user

If you want to stay away from untested code, you should pick previous minor release, e.g. if the current version is 1.4.3 grab 1.3.* version instead.