Skip to content

Release procedure

Jump to bottom Edit New page
Angel Fernando Quiroz Campos edited this page Jun 2, 2020 · 40 revisions

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

This page is meant as a checklist for the packager.

Steps to release

Quality assurance

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

  • Updated changelog
  • WAI/WCAG AAA level approval, at least for the public pages (use AChecker.ca to check)
    • Optionally, check that WAI/ATAG and WAI/ARIA are also respected
  • Verify that there are more automated tests than in the previous version, and that they return positive results (see behat results on Travis-CI )

Version numbering

Version number specification: SemVer

Making 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 the Chamilo translation tool before checking the git code to create the release package.

’’’Do not’’’ first create the release package 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 {} php -l {}

With the current system for 1.11.x, the zip generated by the translation system is usually imported through this command:

mv ~/Downloads/translations.zip . && unzip -o translations.zip && rm translations.zip && git commit -m "Update language terms" . && git push origin 1.11.x

Minified JS (major versions only)

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 (major versions only)

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/

Chamilo started using Composer in 1.10.0. Since then, we have decided the following

  • composer.json is included in git in general
  • composer.lock is included in git only for the release branch
  • the vendor/ folder contents are only included in git in the release branch

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 (@ywarnier & @jmontoyaa) decided that, to solve this issue, we should release a new branch, with the vendor folder included, for each release. These branches remain static (one branch just before adding the vendor folder with its contents) after the release, and are deleted once the stable release is public.

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 -o //to "optimize autoload classes" - see https://getcomposer.org/doc/articles/autoloader-optimization.md
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

Because Chamilo is relatively conservative in terms of PHP support, you must use the composer update command on a configuration that uses the lowest-accepted version of PHP.
This might be tricky and might require the use, for example, of Docker, to load a previous Ubuntu distribution (for example, Ubuntu 14.04 still offers PHP 5.5, but 5.4 is already impossible to find in May 2017 – although you could still find PHP 5.3 on Ubuntu 12.04).

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 bad… 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"
    };

To avoid that, we simply delete the .git subdirs from vendor/:

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 (which is generally executed once in a while during development and doesn’t have to be executed at the moment of packaging anymore) is like this:

vim bower.json (update version, or add a new library)
bower update --force --production
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 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 basic zipping and taring of your package automatically (based on a tag). However, to enable the measurement of the number of downloads and their subsequent tracking here:
https://api.github.com/repos/chamilo/chamilo-lms/releases
You will need to upload these same files as “Assets”. This is done by simply downloading the files and uploading them again, but you will need a high bandwidth to do so because Github closes the connection after a few minutes (5’, we think).

Also, because of the differences in PHP libraries between PHP 5 and 7, we started to package 1.11.6 and following for PHP 5 and 7 separately (on 5.6 and 7.0).
This requires the packaging to be either made with the “platform” setting of composer.json, or by running composer on the corresponding platform.

As an example, composer.json has a “config” section near the end. You should add the “platform” component, like so:

    "config": {
        "component-dir": "web/assets",
        "platfom": {
            "php": "5.6"
        }
    }
}

When generating PHP-version-specific packages, the procedure is the following:
git clone [...] 
mv chamilo-lms chamilo-1.11.x
cd chamilo-1.11.x
vim composer.json  // add platform section here with PHP 7.0
composer update
vim .gitignore // remove last lines
cd ..
tar zcf chamilo-1.11.x-php7-.tar.gz chamilo-1.11.x
zip -r -9 chamilo-1.11.x-php7.zip chamilo-1.11.x
# repeat for PHP 5.6

(and upload manually as asset, as described above)

Lasting branches (major versions only)

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 (STABLE versions only)

  • Update version in www.chamilo.org/version.txt (only on stable releases) – make sure it doesn’t contain unnecessary blank spaces
  • Update the milestones on https://github.com/chamilo/chamilo-lms/milestones

Promotion/Announcements

  • update news in every language on [http://www.chamilo.org]
  • update download page in every language on [http://www.chamilo.org]
  • update pages on Wikipedia (and links to French/Spanish/Dutch/German at the very least)
  • send announcement in Chamilo’s newsletter
  • change details on this wiki
  • announce in the forum (possibly change forum names)
  • announce on Twitter
  • announce on Facebook https://www.facebook.com/chamilolms
  • announce on LinkedIn https://www.linkedin.com/company/888068
  • Link from digg
  • announce on e-magister
  • announce on Xing
  • Press release to the eLearning Guild
  • Press release to PCWorld
  • info at americasistemas dot com dot pe
  • Also notify these bloggers:
  • http://pipwerks.com/2010/01/19/not-so-crazy-about-moodle-try-chamilo/
  • http://ojulearning.wordpress.com/2010/11/17/la-plataforma-mas-opensource-de-las-opensource-chamilo-org/
  • http://www.rtvciplima.com/2011/07/05/marketeando-e-–-learning-ensenanza-a-distancia/
  • [http://osmoney.com/education/chamilo/ Review: Chamilo one of the best e-learning collaboration platforms]
  • http://www.awt.be/ info at awt dot be
  • la liste Interlug de l’AFUL (français)
  • LinuxFR: http://linuxfr.org/
  • Bsoco
  • G2Crowd

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

Add a custom footer

Chamilo LMS

Clone this wiki locally