Release procedure
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.
Before preparing the release, a few things have to be taken care of:
- Updated changelog
- Updated installation guide
- WAI/WCAG AAA level approval (https://achecks.org/achecker/ → options: check AAA)
- Try to have more automated tests than in the previous version, and that they return positive results (see https://github.com/chamilo/chamilo-lms/actions)
Version number specification: SemVer
Making sure the correct version number and stability is used in:
- the various readmes, installation guides, …
- main/install/version.php
Don’t forget to commit the latest language files from the Chamilo translation tool before checking the git code to create the release package.
- download updated language files from https://translation.chamilo.org/
- overwrite translations/messages.*.po with those
- `php bin/console chamilo:update_vue_translations`
- git commit -m “Language: Update language terms” assets/locales translations
- git push origin master
Composer is launched during packaging, in a new pristine clone of the project:
- git clone -b master —depth 1 https://github.com/chamilo/chamilo-lms chamilo
- cd chamilo
- vim .env.dist # change APP_ENV from ‘dev’ to ‘prod’
- composer update -o
- yarn install && yarn encore prod
- touch .env #empty file
- sudo chmod -R 0777 var/ config/ .env
- rm -rf tests
- cd ..
- tar zcf chamilo2.0.0-alpha.1.tar.gz chamilo
- zip -r -9 chamilo2.0.0-alpha.1.zip chamilo
Launch the composer update command using the lowest supported PHP version. This will increase the portability of the package.
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 tag (to see all tags)
git tag -a v2.0.0-alpha.1 -m "Tagging 2.0.0 code - creating Alpha 1"Tags in git are local, so if you don’t push them, they won’t be on the server
git push origin v2.0.0-alpha.1git tag -d v2.0.0-alpha.1
git push origin :refs/tags/v2.0.0-alpha.1git tag NEW OLD
git tag v2.0.0 CHAMILO_2_0_0_STABLE
git push origin v2.0.0
git push origin :refs/tags/CHAMILO_2_0_0Once 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. v2.0.0) then set a title (i.e. 2.0.0) 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).
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"
}
}- 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
- 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
- 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
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 restartAt this point you can install Chamilo and test it.
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)
- 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 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)
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.xMake 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.
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()
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-releasesBecause 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).
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-releasesAdditionally, 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-alphaSome 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.
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 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.1git tag -d v1.11.0-rc.1
git push origin :refs/tags/v1.11.0-rc.1git 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_0Once 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
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.xJust 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
- 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
- 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
- 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
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 restartAt 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 updateand 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
-
Home
- Tools and sessions
- Quiz: Importing
- Releases
- Community support strategy
- Translation management
- How to report issues
- Development
- Integration