Release procedure

Note: To know more about when we decide to release, please check the Release cycle article.

Quality assurance

Before you prepare the release, a few things have to be taken care of:

The 10 steps to release

Version numbering

Version number specification: http://semver.org/

Make sure the correct version number and stability is used in:
  • the upgrade/install script main/install/index.php ($new_version = ...)
  • the various readmes, installation guides, ...
  • update chamilo.org/doc/installation_guide.html (only on stable releases)
  • main/install/version.php (make sure you check this one, it is usually forgotten)

Language files

Don't forget to commit the latest language files from DLTT before checking out (export) the cvs code to create the release package.

'''Do not''' first create the release package from cvs and then add the DLTT, this will cause problems (having a release tag that doesn't include new language files is one of them).

You can check the validity of the PHP in language files with the following command:

find . -name "*.inc.php" -type f -print0 | xargs -0 -I {} php5 -l {}

Minified JS (only for major versions)

Make sure all JQuery-related files (main/inc/lib/javascript) are loaded as .min.js versions (load a page, view source with CTRL+u, check everything says ".min.js" if there is such an option).
However, there are some exceptions to that rule (some minified libraries just don't work well), as is the case with fcbk, so make sure you extra-test all the features that relate to those libraries you change.

Upgrade procedure button (only for major versions)

When releasing test or alpha versions for a major version without working upgrade procedure, disable the upgrade button in the installer.
This is done in the main/install/install.lib.php, at the end of display_requirements()

Composer and vendor

Starting from version 1.10.0, Chamilo uses Composer (a lot). As such, we have had to decide the following
  • composer.json is included in git
  • composer.lock is included in git (although this might be an additional hassle for developers during the development period as conflicts may arise if they do not "composer update" each time they "git pull")
  • the vendor/ folder contents are not included in git

As such, the release procedure requires something special, as we want Github to include the vendor/ directory in the final ZIP package that it will generate.
We (Julio and Yannick) decided that, to solve this issue, we should release a new branch, with the vendor folder included, for each release. These branches would remain static (one branch just before adding the vendor folder with its contents) after the release.

The procedure thus becomes something like this (assuming you are preparing 1.10.0 alpha):
  • git checkout -b 1.11.0-releases
  • vim .gitignore (and remove the 3 last lines with vendor and composer)
  • composer update
  • composer install
  • //The following command is not always necessary but it might fix submodule issues immediately - see section below
  • find vendor -name ".git" -type d -print0 | xargs -0 -I {} rm -rf {}
  • git add composer.lock vendor web
  • git rm -r tests
  • git commit -m "Add static resources and remove tests dir for release"
  • git push origin 1.11.0-releases

Submodules issues

When including "dev" stability modules through Composer, if a Git repo is available for the library, Composer will download it from Git (including the .git folder) instead of downloading a simple package of files.

This is really a bad idea... not only does it mean you are packaging a stable software with a (presumably) unstable library, but it also means that, when doing the steps above of git adding vendor, in reality the git submodule will not be added to your release-specific git repo.

To fix this, follow this procedure (preferably):
  • if the repo of the library has a stable release (or a tag) that matches your need, make composer.json depend on this tag instead of "dev".
  • if the repo doesn't have a stable release, and they don't want to add one (like the guys at iCalcreator), then you'll have to fork their repository, add a tag (without the "v" in the version number) by yourself (in the same branch as the "dev" you were depending upon) and add a hack in the repositories section of your composer.json, like this:
        "repositories": [
            {
                "type": "vcs",
                "url": "https://github.com/ywarnier/essence" 
            },
            {
                "type": "vcs",
                "url": "https://github.com/ywarnier/iCalcreator" 
            }
        ],
        "require": {
            ...
            "essence/essence": "2.5.3",
            "kigkonsult/icalcreator" : "0.1.0" 
        };
    

This is awful, but the alternative (removing the .git directory manually from vendor, then adding the directory manually) is even uglier (when it works). If that doesn't work (sometimes it doesn't, we couldn't find why yet), you can use a "branch" name preceded by "dev-", like this:

  "essence/essence": "dev-jmontoyaa-patch-1",

In this very specific last case, you will probably have to add the lib manually to avoid it to be considered a Git submodule and come out empty in the package. To do that :

find vendor -name ".git" 
# and for each of them:
git ls-tree HEAD vendor/essence/essence
git rm --cached vendor/essence/essence
git rm --cached vendor/essence/essence/cli
rm -rf vendor/essence/essence/.git*
git add vendor/essence/essence
git commit -m "Add essence lib manually" vendor/essence/essence
git push origin 1.11.0-releases

Bower assets

Additionally to update the external JavaScript librarys located in app/Resources/public/assets the procedure is like this:
  • vim bower.json (update version, or add a new library)
  • bower update --force
  • composer install
  • git add app/Resources/public/assets/
  • git commit -m "Update bower assets"
  • git push origin 1.11.0-alpha

Release date

Try not to officially announce a release on a Monday or a Friday. Monday is the day the most people will come to you about something that doesn't work so you will be busy answering them, plus you might still be recovering from that crazy week-end. Friday doesn't give you any chance to fix something in a hurry if you missed something out.

Git adding submodules

Sometimes, some folders might not be added to the packaging branch because they once contained a git submodule.
This can be fixed following the procedure in #7889 (comment 11)

Git tagging

  • git tag (to see all tags)
  • git tag -a v1.11.0-rc.1 -m "Tagging 1.11.0 code - creating RC 1"
    Tags in git are local, so if you don't push them, they won't be on the server
  • git push origin v1.11.0-rc.1

Deleting a tag

  • git tag -d v1.11.0-rc.1
  • git push origin :refs/tags/v1.11.0-rc.1

Renaming a tag

"git tag NEW OLD"

git tag v1.11.0 CHAMILO_1_11_0_STABLE
git push origin v1.11.0
git push origin :refs/tags/CHAMILO_1_11_0

Github releases

Once you have tagged your release and pushed the tag, you'll have to take another extra step to officialize this tag as a release on Github.
Go to https://github.com/chamilo/chamilo-lms/releases/new and select your tag (i.e. v1.9.8) then set a title (i.e. 1.9.8) and save.
If this is not a stable release, tick the box at the end of this small form ("This is a pre-release").

Ideally, the description of your release will contain the same text as your changelog introduction for this version, and the new features available.

Github will take care of the zipping and taring of your package automatically (based on a tag), so you don't have to worry about that anymore.

Branches

When releasing a major version, you might need to branch between head and a branch for the minor bugfix versions.
Call the new branch by the name of the previous major version + : for example, "1.9.".

For example, if releasing v10."something" and starting to work on the next major version v11, you will need to create a 10.x branch, that you will use for later applying security patches and release one or more "security fix" releases.

To create a new branch (let's say 1.10.x when 1.9.x is finished):

git checkout -b 1.10.x
git push origin 1.10.x

Just in case you would like to switch branches from master to something else (like it was done for 2.0 with the 1.10.x branch), you can refer to this solution: http://stackoverflow.com/a/2862938/1406662

Publish

  • By default, the Chamilo zip will be auto-generated on Github (because of the tag). Sadly, some users (Cuba) are not able to access servers in the US, so you have to provide an alternate download. This is why all downloads should also be provided from our servers. (this should be OK now with the embargo removal?)
  • Upload zip to Chamilo's CDN (make sure permissions are alright), preferably in zip AND tar.gz format
  • Update version in www.chamilo.org/version.txt (only on stable releases) - make sure it doesn't contain unnecessary blank spaces
  • Update this public wiki's versions pages: Chamilo_versions_history
  • Update the milestones on https://github.com/chamilo/chamilo-lms/milestones

Promotion/Announcements

Although not public, the following link might be useful as well: https://support.chamilo.org/projects/board/wiki/Press_communications_contacts