| name | update-changelog |
| description | Update public/documentation/changelog.html with commits for a new Chamilo release. Applies the filtering and formatting rules from tests/scripts/packaging/gitlog.php, classifies commits into changelog categories, and reports a line-count summary per category. Use when the user wants to update the changelog, prepare a release entry, add a version section, or runs /update-changelog.
|
Update Changelog
Update public/documentation/changelog.html with the commits for a new Chamilo
release. The changelog is progressive: a version section may be created and
updated multiple times before the release tag is actually set. Handle both cases.
Step 1: Determine the target version
Ask the user: "Which version number are we adding or updating? (e.g. 2.0.4)"
Once you have the version, check whether a section for it already exists in
public/documentation/changelog.html by looking for <a id="X.Y.Z">.
Step 2: Determine the commit range
The range is "commits not yet listed in the changelog for this version". How to
find it depends on whether the section already exists:
If the section already exists (progressive update):
- Extract every commit SHA already present in that version's
<li> entries.
- Run
git log --pretty=format:'%H' HEAD and skip every SHA that appears (by
its 8-char or 12-char prefix) in the existing section.
- The range to process is everything since the newest already-listed commit.
Concretely: find the most recent commit in the section, then use
git log --pretty=... <that-SHA>..HEAD as the range.
- If the section exists but has no
<li> entries yet, fall back to the
previous-release tag as the start point (see below).
If the section does not yet exist:
- Identify the most recent existing release tag on this branch via
git tag --merged HEAD --sort=-version:refname | grep -E '^v[0-9]'.
- The most recent tag is the start of the range:
git log v2.0.X..HEAD.
- If the tag name is ambiguous (e.g.
v2.0.2 vs 2.0.2), ask the user to
confirm before running the log command.
Step 3: Apply the gitlog.php filtering rules
Read tests/scripts/packaging/gitlog.php to confirm the rules are unchanged
before processing. Then apply them in this order to each commit's subject line:
3a. Hard-skip entire commits whose subject starts with any of:
Update language termsUpdate language varsUpdate lang varsMerge (also lowercase merge)Scrutinizer Auto-FixesUpdate changelogFix PHP Warning
Also skip any commit whose subject starts with Minor (case-insensitive,
first 5 characters — matches Minor, MINOR, minor:, etc.).
Note: gitlog.php defines a $skipTechnicalPrefixes array (QA, Internal,
Display, Fix, Refactor, Migration, UI, …) but never uses it — it is dead
code. Do NOT filter on those prefixes; the existing changelog includes
Internal:, Display:, and Fix: entries.
3b. Normalise separator punctuation (applied in this exact order):
^(\w+) - (.*) → $1: $2^(\w+ \w+) - (.*) → $1: $2^(\w+) : (.*) → $1: $2
3c. Rename known prefix mistakes via sanitizeCategory():
Apply the full substitution table below (case-insensitive prefix match,
replace prefix only, keep the rest of the message):
| Wrong prefix | Correct prefix |
|---|
| Quiz / Exercises | Exercise |
| LP / Learning Paths / LearningPath / Learnpaths | Learnpath |
| Documents | Document |
| Announcements | Announcement |
| RemedialCourse | Plugin: RemedialCourse |
| Groups / [usergroup] | Group |
| Survey report / Survey list export | Survey |
| Learnpath report | Learnpath |
| TopLink / TopLinks | Plugin: TopLinks |
| Sessions | Session |
| Cas | Authentication: CAS |
| Webservices / WebService / Web services | Webservice |
| BBB | Plugin: BigBlueButton |
| My Progress / My Progres / Reports / Reporting | Tracking |
| Courses | Display |
| [LP] | Learnpath |
| Student follow page | Tracking: Student follow-up |
| REST | Webservice: REST |
| Import CSV / ImportCSV / Import_csv.php | Admin: CSV import |
| [Minor] | Minor: |
| [admin] | Admin |
| MySpace | Tracking |
| Career diagram / Careers | Career |
| Users | User |
| Style: | Display: |
| Course Announcement | Announcement |
| Testing / CI | QA |
| Blogs | Blog |
| Gradebook eval | Gradebook |
| Survey test | QA: Survey |
| Editor | WYSIWYG |
| Global | Internal |
| Extra field | Extra Fields |
| Settings | Admin |
| Changelog | Documentation |
| Session import | Admin: Session import |
| XAPI | xAPI |
| CourseCopy / Course Copy | Maintenance |
| Course Backup | Maintenance |
| SSO | Authentication: Single Sign On |
| Skills | Skill |
| Messages | Message |
| Security fixes - | Security: |
| Work / Works / Pending works | Assignment |
| Improve code | Internal: Improve code |
| Thematic / Thematic advance | Course Progress |
| Agenda | Calendar |
| Course import | Maintenance |
| Student publication / Student publications | Assignment |
3d. Strip issue references from the message text:
If the subject matches ((BT)?#\d{2,5}), remove the first match and anything
after these patterns: see ISSUE, - ref, -refs, - refs, ISSUE.
3e. Finalise:
Apply ucfirst() (capitalise the first character of the message).
Step 4: Classify commits into categories
Use the normalised message prefix (the part before the first :) to assign
each commit to a category. Apply in priority order — stop at the first match:
| Category | Message prefix matches (case-insensitive) |
|---|
| Security fixes | Security |
| Fixed | Fix, Bug, Install, Language, Hotfix |
| Added | Add, New, Enable, Feature, Implement, Create, Include, Introduce |
| Removed | Remove, Delete, Drop, Deprecate |
| Changed | Everything else (Internal, Display, Refactor, Plugin, Auth, Learnpath, Exercise, …) |
Omit a category section entirely if it has zero entries.
Step 5: Build each <li> line
Format (newest-first, matching existing changelog style):
<li>[YYYY-MM-DD] (<a href="https://github.com/chamilo/chamilo-lms/commit/SHA12">SHA8</a>) Message</li>
When a BT# or GH# issue link exists, add it between the commit link and the
closing ):
<li>[YYYY-MM-DD] (<a href="https://github.com/chamilo/chamilo-lms/commit/SHA12">SHA8</a> - <a href="https://task.beeznest.com/issues/NUM">BT#NUM</a>) Message</li>
Where SHA12 = first 12 chars of the full SHA, SHA8 = first 8 chars.
Correct any obvious typos in commit messages when formatting for publication
(the HTML is user-facing; the git history is not changed). Note corrections in
the final report.
Step 6: Ask for the release codename
Ask: "What codename should I use for version X.Y.Z? (Leave blank to insert a placeholder)"
- If provided, use it:
Chamilo X.Y.Z - Codename, YYYY-MM-DD
- If blank, use:
Chamilo X.Y.Z - [TBD], YYYY-MM-DD
- Use today's date as the release date unless the user specifies another.
- Historical context: codenames have been small cities/towns/villages in the
Somerset/Cheddar region of England (Cadbury, Blackford, Little Weston, Axbridge).
Step 7: Write or update the changelog
If the section does not yet exist: insert it above the previous release's
<a id="..."> anchor. Also add an entry to the <div class="toc"> <ul> at
the top, above the previous release's TOC line.
If the section already exists (progressive update): append the new <li>
entries into the correct category <ul>. If a commit's category <h3> block
does not exist yet in that section, create it in the correct order:
Security fixes → Added → Changed → Fixed → Removed → Known issues.
The release summary <p> should be written or updated to reflect the nature of
the commits in this update. If the section is new, write a brief paragraph. If
updating an existing section, revise the summary if the new commits materially
change its character.
Step 8: Report
Print a summary table:
Changelog updated for Chamilo X.Y.Z - Codename
Category | Lines added
-----------------|------------
Security fixes | N
Added | N
Changed | N
Fixed | N
Removed | N
Total | N
Filtered out (not included):
- M merge commits
- K minor/noise commits
Typo corrections applied:
- <SHA8>: "<original>" → "<corrected>" (or "none")
Guidelines
- Always read
tests/scripts/packaging/gitlog.php at the start to check for
rule changes before applying the filter logic above.
- The changelog is the user-facing record. Prefer clarity over verbatim
faithfulness to commit messages.
- Never invent commits. Only include SHAs that appear in the git log output.
- Do not modify any section other than the target version.
- If the user provides a specific date, use that; otherwise use today's date.
