Skip to content

Release procedure

Jump to bottom Edit New page
Yannick Warnier edited this page Aug 31, 2023 · 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 WAVE evaluation tool to check https://11.chamilo.org and the homepage – and the documents tool homepage – of a public course)
    • 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 https://github.com/chamilo/chamilo-lms/actions )

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 = …) (only for major versions)
  • the various readmes, installation guides, …
  • 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 4 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

Security check in assets

Some of the libraries updated through bower (or any JS dependencies management system) might pull code that has a potential for security flaws. Updating bower should be immediately followed by a check on those additional folders and files that could potentially introduce security issues. Demo code, documentation and upload-related scripts that do not go through Chamilo’s validation should be immediately removed before getting included into Git.

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 (including a few optimizations for smaller downloads). Using composer tricks to fake a PHP version does not work, so setting up a virtual machine with the help of a blog post is usually a good idea:
apt install php-cli zip unzip
# cd /root ; install composer from https://getcomposer.org/download/ ; cd /var/www
git clone -b 1.11.x --depth=1 https://github.com/chamilo/chamilo-lms chamilo-1.11.x
cd chamilo-1.11.x
composer update -o --no-dev
# takes about 8' for PHP 7.2 and 20' for PHP 5.6. Plan for at least 8GB RAM for PHP 5.6
find vendor -name '.git' -type d -print0 | xargs -0 -I {} rm -rf {}   
rm -rf tests
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 on a different machine

(and upload manually as asset, as described above)
For PHP 5.6, you may need to install specific packages – check the end of this blog post

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

Public packaging

  • Edit the image on DigitalOcean’s marketplace
  • Edit the image on Docker hub
  • Edit the AWS image

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

Testing/packaging procedure

Once all the technical steps above have been completed, you are ready to setup the environment to test and package Chamilo.
Build a virtual machine (Ubuntu server 20.04 or something like that) and execute the following commands as root.

apt update && apt -y upgrade && apt install apache2 libapache2-mod-php mariadb-client mariadb-server php-dev php-gd php-curl php-intl php-mysql php-mbstring php-zip php-xml php-cli php-apcu git unzip && mysql_secure_installation
mysql -u root
grant all privileges on chamilo.* to chamilo@localhost identified by 'chamilo';
exit
cd /var/www/ && rm html/index.html && git clone --single-branch --depth 1 -b 1.11.x https://github.com/chamilo/chamilo-lms html
cd /root/ && mkdir composer && cd composer && php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && php composer-setup.php && php -r "unlink('composer-setup.php');" && mv composer.phar /usr/local/bin/composer && cd .. && rm -rf composer
cd /var/www/html && git checkout tags/v1.11.14
composer update
;; long process here
chown -R www-data: app main/lang main/default_course_document/images/ web
vim /etc/apache2/sites-available/000-default.conf
;; Add the following block anywhere inside the vhost block:
RewriteEngine on
<Directory /var/www/html>
    Options Indexes FollowSymLinks MultiViews
    Require all granted
    AllowOverride All
</Directory>
^esc:wq
a2enmod rewrite
service apache2 restart

At this point you can install Chamilo and test it.

Now you can also try with other PHP versions.

apt install software-properties-common && add-apt-repository ppa:ondrej/php
apt update
apt remove libapache2-mod-php php-{dev,gd,curl,intl,mysql,mbstring,zip,xml,cli,apcu}
apt remove libapache2-mod-php7.4 php7.4-{dev,gd,curl,intl,mysql,mbstring,zip,xml,cli,apcu}
apt install libapache2-mod-php7.1 php7.1-{dev,gd,curl,intl,mysql,mbstring,zip,xml,cli,apcu}
rm app/config/configuration.php
rm -rf vendor/*
rm composer.lock
composer update

and proceed with the installation again.

If everything goes according to plan, you can proceed with the packaging.
Choose the lowest supported PHP version for packaging (see above).

cd /tmp
git clone --single-branch --depth 1 -b 1.11.x https://github.com/chamilo/chamilo-lms chamilo-1.11.x
cd chamilo-1.11.x
composer update -o --no-dev
find vendor -name '.git' -type d -print0 | xargs -0 -I {} rm -rf {}   
rm -rf tests
cd ..
tar zcf chamilo-1.11.x.tar.gz chamilo-1.11.x
zip -r -9 chamilo-1.11.x.zip chamilo-1.11.x
# repeat for other PHP major versions
# once you have everything tested, upload the files to a "release" on Github
Add a custom footer

Chamilo LMS

Clone this wiki locally