Skip to content
Claudio Guidi edited this page May 28, 2021 · 2 revisions

The following are general rules for contributing to the Jolie codebase. We try our best to apply common sense in all situations: please get in touch if you have any doubt.

Terminology

We use semantic versioning, MAJOR.MINOR.PATCH, slightly adapted to a language:

  • Major releases might mean that code in a previous major release cannot even be parsed.
  • Minor releases might drop support for some libraries.
  • Patch releases are stable: they are used for minor improvements and bugfixes.

Some additional terminology:

  • A major series is a series of releases with the same major version.
  • A minor series is a series of releases with the same minor version.

All releases are tagged in master.

Branch structure

  • master is the branch for the development of the next release. The maintainer pulls patches to this branch from feature and fix branches.
  • By default, master is for developing the next patch release. The maintainer announces when master switches to developing the next minor (or major) release.
  • When a new release is made, it is tagged in master.
  • Feature development is done in feature branches. For example, a branch for developing a new cool feature would be called feature/cool.
  • Fixes are developed in fix branches. For example, a branch for developing a new very-necessary fix would be called fix/very-necessary.
  • Past release series that offer fixes might have release branches (see more about this in the part about updating past release series).

Workflow for features and fixes for the next release

  1. Always begin by ensuring that you are in line with master, by pulling, or by forking or cloning if you are starting from scratch.
  2. Create and enter a new branch, called feature/name-of-feature if you are developing a feature or fix/name-of-fix if you are developing a bugfix.
  3. Work on your branch.
  4. If your feature takes a long time to develop, make sure to pull from master and rebase every now and then. This will help you in avoiding a nasty alignment down the road.
  5. Make sure that tests are included, if reasonable.
  6. Once you're done developing, open a pull request to master.

Workflow for updating a past release series

This section covers what to do when you want to update an old release series. Below, for example, we assume that master is on version 3.20 and you need to apply a feature or fix to version 3.19.

First, you have to figure out your starting point. Check whether a release branch for your version of interest exists already; in our example, this means checking whether a branch called release/3.19 exists or not. If it does, that is your starting point. Otherwise, you should checkout on master the tag v3.19 and that is your starting point. (Do not create a release/3.19 branch yourself, that will be done when your work is merged.)

Create a branch called fix/3.19/name-of-fix (for a fix) or feature/3.19/name-of-feature (for a feature), and start working. When you are done, check if your code can be easily applied to master:

  • If so, create a fix or feature branch for it and do it. When you do the pull request, point out that you have done both.
  • If not, create a fix or feature branch for it and, if possible, add a test that should pass once the fix or feature is completed. Open an issue where you describe why you have not been able to patch master.

In general, if there is a fix (or feature like a new API) for version X, we want all versions that follow (version Y > X) to have the fix included as well whenever it makes sense.

General rules

  1. When you make a pull request, the maintainer examines it as soon as reasonably possible. If it is satisfactory, it is merged. If modifications are needed, the pull request will be closed with comments and you might be asked to reopen it once you complete the necessary modifications.
  2. It is your responsibility that the pull request is minimal, by appropriate rebasing if necessary. If the pull request is too long to be reviewed, it might be closed and you might be asked to make it more manageable to review.
  3. Well made pull requests will be given priority.

Diagram

Diagram of jolie branches