Child pages
  • Version Control System Philosophy of TSPHP
Skip to end of metadata
Go to start of metadata

Structure

TSPHP uses two main branches. "master" which points at the most resent released version and "dev" which is used as development branch for a new version. One should always work on the dev branch (or on a specific branch if it was created for a particular feature). Logically, pull requests should also be made against dev.

I recommend to read the following post if you are not yet familiar with Git, GitHub respectively:
https://github.com/skyscreamer/yoga/wiki/GitHub-Best-Practices

Principles

The developer should apply the following principles concerning version control system:

  1. Commits should be as small as possible. Preferably one change per commit. That does not mean that a commit for every changed character is necessary, but for each resolved issue and if it is a big issue for each sub-problem of the issue. It is perfectly fine to have several commits within one push tough.

  2. Follow the following commit message guidelines (adopted from http://git-scm.com/book/ch5-2.html)
    Each commit comprises a title and a body where the title is the issue number following by its title and the body (separated by a blank line from the tile) mentions what has been done. The title should ideally be not longer than 50 characters and 100 at max. Try to be more concise (and rewrite the title in JIRA as well) if the title is longer than 100 characters long. An example

    TSPHP-77 grammar for simple calculator
    
    added + - * /, still missing are ^ ( )

    If you have solved more than one sub-problem within one commit, then preferably list the sub-problems as follows:

    TSPHP-77 grammar for simple calculator
    - added + - * /, still missing are ^ ( )
    - grouped operators in one rule

    In the case where you have solved more than one issue within one commit (try to avoid this whenever possible, commit regularly as mentioned in point 1 above), then use the most important issue as title. Further issues follow the same principle as above and are separated with blank line from the comment of the previous issue. Following an example:

    TSPHP-820 Falseable types
    - introduced new modifier for falseable types
    - removed nullable scalar types -> information is stored in ICanBeNullable
     
    TSPHP-759 casts not over multiple levels
     
    - removed the corresponding behaviour
    - adopted the tests accordingly
  3. Make a branch per independent issue, this way you can create several pull request at the same time.
  4. Make sure to run the ant target dist on your local machine before creating a pull request. Check that all tests pass and that the code quality is allright (consult QA.html in the /build/ folder)
  5. Make sure that you have included tests for new functionalities or that tests cover your changes before you create a pull request.
  6. Do not commit products (code/artefacts etc.) which are a result of a build or a result of another generation utility.
  7. It is recommended to commit and create pull requests regularly and to fetch regularly from the upstream repository (from GitHub) to avoid conflicts

 

New builds are created by the build server each time someone pushes changes back to the remote git repository at the moment. Thus the developer should have a look at the results of the build server (does the build fail? Are there new checkstyle warnings, pmd warnings etc.)

Versioning scheme

The following versioning scheme takes place as long as TSPHP has not released a first major version: 0.M.I

Whereas M stands for milestone and I for iteration. A milestone is at the end of an iteration if I is 0 and that means I is just before achieving milestone M. Otherwise the Iteration I is the Ith iteration after M. Following some examples:

0.1.0 = Iteration just before milestone 1 - achieving milestone 1 after this iteration
0.1.1 = Iteration 1 after Milestone 1 (next milestone is milestone 2)
0.1.2 = Iteration 2 after Milestone 1 (next milestone is milestone 2)
0.2.0 = Iteration just before milestone 2 - achieving milestone 2 after this iteration