How to manage branches and versions when developing on the PLFM and client GIT projects

Our strategy is to give PLFM a master branch and also an API-stable branch. Developers changing the master branch are not responsible for immediately verifying that the changes work with clients (and may even purposely 'break' the current AP(s). However, changes to this branch are not immediately available to the clients. Workers changing the API-stable branch are responsible for testing (perhaps after making corresponding changes to) the clients and making sure they work.

PLFM Branch Choice	Advantages	Disadvantages
master	May 'break' client; need not verify client functionality.	Changes are not immediately available to client developers.
API-stable	Changes are immediately available to client developers	Developer must ensure client functionality.

Workflow

(to edit diagram, go to https://docs.google.com/a/sagebase.org/drawings/d/1s2zCr57TOajuuMHnD8xMXWVIWmPDINNE-MTFSMlNx4U/edit)

Development Workflows

Local PLFM changes

If you're working on PLFM and the changes *don't* need to be used immediately by clients, then you may work off of the 'master' branch. Pull from the remote master, create a branch for your work, code and test, then merge back into master and push to github.

Local Client changes

If you are just working on a client then you may work off the 'master' branch of the client's project, following the pattern described above. The client will depend on the API-stable branch.

Changes to PLFM and Client

If you are making changes to PLFM's API and also are changing a client to reflect these changes, then:

(to edit diagram, goto https://docs.google.com/a/sagebase.org/drawings/d/1X05G5t_8tzW8lQjroQQk3HH9aTHYyvFZfPMg1eckTuU/edit)

- pull from the client's master branch (creating a local branch for development)

- pull from the PLFM's stable branch, which will have a name like '0.13.1'.

- develop and test locally

- run pomVersioner.py to increment version, e.g. from 0.13.1.1 to 0.13.1.2

- push to 0.13.1

- push to the client's master branch

- on PLFM, git checkout master

- pull from remote

- merge the API-stable branch's changes

- resolve any conflict and get a clean build

- run the pomVersioner to restore the master's version, e.g. to 0.13.2-SNAPSHOT

- push to the PFLM master branch

Incorporating PLFM master with the API-stable branch

(to edit, go to : https://docs.google.com/a/sagebase.org/drawings/d/1WUtUpzq1vtbv9nd1o3S3Dq_cUbLoDczDFqZBv3Pl3PI/edit)

Pull from PLFM master

- on master, 'git checkout -b 0.13.2' to create the new branch

in the client project, pull from master, changing the version to be the version of the local PLFM snapshot (0.13.2-SNAPSHOT)

work to make client and PLFM work together

in PLFM branch, change version to 0.13.2.1 and push

in client master, change version to 0.13.2.1 and push

in PLFM master, merge the branch, change version to 0.13.3-SNAPSHOT and push to remote

Browser not supported