July 1, 2024 — Regardless of what languages you write your programs in, you probably maintain files like changeLog.txt or releaseNotes.txt.

Change logs are very helpful for:

informing your users of new features and bug fixes
providing detailed technical information to your development team (and open source contributors)
periodical data analysis for strategic project planning - how fast are we shipping new features? fixing bugs? breaking things?

What if there was 1 language that let you do all 3 things at once?

*

Introducing Changes, a microlang (only 70 lines of code, including comments) that makes it as concise as possible to write, read and analyze change logs.

Changes generates a pretty HTML file for your end users; allows for including unlimited detailed technical information for your developers; and generates summary statistics as TSV, CSV, and JSON for your project managers.

*

There's almost nothing to learn (the code is self explanatory).

In fact, it's almost guaranteed that using Changes you will need to write less (we've taken every unnecessary character out).

*

Example

We use Changes for the Scroll Release Notes.

Be sure to check out the source code that generates that HTML.

*

How to use

Install Scroll

npm install -g scroll-cli

Create a release notes file:

releaseNotes.scroll

title My Release Notes
printTitle
buildConcepts releaseNotes.csv releaseNotes.json releaseNotes.tsv
// You can import the changes parsers or just copy/paste the 70 lines into your own file.
[pathToScroll]/microlangs/changes.parser

thinColumns

📦 0.1.1 7/1/2024
🏥 fixed bug in command line app

📦 0.1.0 7/1/2024
🎉 added command line app

endColumns

Run scroll build

Done! You should now see a releaseNotes.html file as well as a TSV, CSV, and JSON file.

*

What do you think? Anything that should be added/removed/improved?

⁂

Changes: A Microlang for Change Logs

Example

How to use

Related