Integration Procedures

The below examples assume upgrading from 3.5.2 to 3.5.3 (LAE15.0.2 to LAE15.0.3).

Part Zero: Setup local repository

1. git clone [email protected]:CLAMP-IT/moodle
2. cd moodle
3. git remote add core [email protected]:moodle/moodle
4. git fetch core

Part One: Create integration branches

Stable (base) branch

1. git checkout LAE_35_STABLE (current stable branch with core hacks only, should correspond to LAE 15.0.2).
2. git checkout -b LAE_1503_STABLE (create new integration branch named after version number, so LAE_1503 would be LAE 15.0.3)
3. Revert any CLAMP-specific changes which have been superseded by incoming core changes (check Redmine and #integration in Slack).
4. git merge v3.5.3 (merge in new core code)
5. At this point integrate any CLAMP-specific fixes via cherry-pick. (We do not rebase because historically they don’t work well with subtree merges)
   • Look for changes in Redmine issues with their target instance set to the new release.
6. Update the LAE_readme.md file. In vim:
   • :%s/3.5.2/3.5.3/g
   • :%s/15.0.2/15.0.3/g
7. Test (push to GitHub and let Travis do the rest)

Package branch

1. git checkout -b LAE_1503_PACKAGE LAE_35_PACKAGE (create new PACKAGE integration branch — includes contrib modules)
2. git merge LAE_1503_STABLE (merge stable integration branch into the new contrib integration branch)
3. For summer releases only pull in new contrib code (see below)
4. Update the manifest (the section in LAE_readme.md describing the contrib modules) if needed
5. Test. We do not run automated tests for package branches, so you should confirm smooth upgrade in a browser.

Pulling in contrib code (modules/plugins/packages) with subtree

Adding a new module to a PACKAGE branch

1. Add the remote (naming it something like gradereport_laeuser)
2. Fetch the remote, then…
3. git subtree add --squash --prefix=grade/report/laeuser gradereport_laeuser 7f9dedcdcf757ef82bfdc7db89f62c7c67559fa9

Updating a module on a PACKAGE branch

1. git remote add [package-name] [package-url]
2. git fetch [remote-name]
3. git subtree pull --squash --prefix=[path] [remote-name] [ref]

For example:

1. git remote add filtered_course_list [email protected]:CLAMP-IT/moodle-blocks_filtered_course_list
2. git fetch filtered_course_list
3. git subtree pull --squash --prefix=blocks/filtered_course_list filtered_course_list v4.2.1

Sanity check: Diff some diffs to confirm your work

The following indicates that our upgrade has accomplished the same thing as core’s except that we have also changed the LAE_readme.md file.

diff <(git diff LAE_35_STABLE...LAE_1503_STABLE --numstat) <(git diff v3.5.2...v3.5.3 --numstat)
1d0
<  LAE_readme.md                                      | 14 ++++--
22c21
<  21 files changed, 172 insertions(+), 61 deletions(-)
---
>  20 files changed, 163 insertions(+), 56 deletions(-)

For the PACKAGE branches you should also see any changes we made to contrib modules, if any:

diff <(git diff LAE_35_PACKAGE...LAE_1503_PACKAGE --numstat) <(git diff v3.5.2...v3.5.3 --numstat)
1d0
< 9 5   LAE_readme.md
20,50d18
< 36    0   report/customsql/README.txt
< 94    0   report/customsql/addcategory.php
< 76    0   report/customsql/categoryadd_form.php
< 67    0   report/customsql/categorydelete.php
< 58    0   report/customsql/classes/event/query_deleted.php
...

Part Two: Tag n' push

Once we’re satisfied with the code we tag and push to origin.

1. git checkout LAE_35_STABLE
2. git merge LAE_1503_STABLE
3. git push origin LAE_35_STABLE
4. git tag -a v3.5.3-LAE15.0.3-base -m 'Moodle 3.5.3-LAE15.0.3 [No plugins]'
5. git push origin v3.5.3-LAE15.0.3-base
6. git branch -d LAE_1503_STABLE (cleanup integration branch locally)
7. git push origin :LAE_1503_STABLE (cleanup integration branch on remote)
8. git checkout LAE_35_PACKAGE
9. git merge LAE_1503_PACKAGE
10. git push origin LAE_35_PACKAGE
11. git tag -a v3.5.3-LAE15.0.3 -m 'Moodle 3.5.3-LAE15.0.3'
12. git push origin v3.5.3-LAE15.0.3
13. git branch -d LAE_1503_PACKAGE
14. git push origin :LAE_1503_PACKAGE

Note that beginning in January 2016 we stopped pushing core code to github.

Notes

Early versions of git subtree reacted poorly to rebasing. Please avoid rebasing if at all possible.

Helpful script for tagging and pushing

git push origin LAE_34_STABLE
git push origin LAE_34_PACKAGE
git push origin v3.4.3-LAE14.0.2-base
git push origin v3.4.3-LAE14.0.2
git push origin :LAE_1402
git push origin :LAE_1402_PACKAGE

git tag -a v3.4.3-LAE14.0.2-base -m 'Moodle v3.4.3-LAE14.0.2 [No plugins]'
git tag -a v3.4.3-LAE14.0.2 -m 'Moodle v3.4.3-LAE14.0.2'

The LAE major version number corresponds to the Moodle release major number, while the patch corresponds to Moodle minor version. The LAE minor version number is reserved for a situation in which we need to bump versions in between official Moodle releases. We increment independently of the Moodle release numbers.