Fastest way to add new version of your Sublime Text package
Possibly outdated data
I wrote this article in January 2018. Some information from it may be out of date.
June 6 2021
- Overview
- Audience
- Relevance
- Motivation
- Demonstration
- Features
- Limitations
- Installation
- Activation
- Usage
- Details
- Problems and non-fixed bugs
- Testing environment
1. Overview ¶
Tutorial, how you can quick to create detailed release and changelog for your Sublime Text package.
2. Audience ¶
Inexperienced developers of Sublime Text 3 packages.
This article may be useful for any non-Sublime Text developers, which makes releases and changelog.
3. Relevance ¶
This article is relevant for April 2018. In the future, the data in this article may be obsolete.
4. Motivation ¶
When I create new release for my Sublime Text package, I need:
- Add changelog to GitHub release page,
- Update CHANGELOG.md,
- Update version in messages.json,
- Add changelog to messages/<version>.txt file,
It may take a lot of time.
In this article I wrote, how possible to make all these actions use solely one command in command line.
5. Demonstration ¶
I push commit to my GitHub repository → I enter in command line:
release-it -n -V
CHANGELOG.md and messages.json:
messages/<version>.txt and package.json:
If you want to have same behavior, read on.
6. Features ¶
Tutorial of this article must be support:
7. Limitations ¶
- Your must host your package to GitHub. If your package on BitBucket, GitLab or another hosting, you can’t make a release via release-it.
- Your commits must be must be compatible with Conventional Commits. List of supported scopes. I recommend use commitizen.
8. Installation ¶
You need to install:
- Node.js and npm, if no;
- git if no, even if you use another VCS;
- UNIX commands tee, cat, mv and sed, if no; for Windows users I recommend install Cygwin and add to your Path environment variable value — path to Cygwin commands folder;
- release-it globally ≥ 7.3.0;
- generate-changelog globally;
- npm js-beautify globally.
9. Activation ¶
You need to create all files from this section in root folder of your package repository.
You can see configuration files of real package in SashaSublime repository.
Caution
I recommend in first do actions from Activation and Usage sections in the test repository, not real. Argumentation:
- You or I can make a typo(s);
- Differences in my and your environments;
- Different versions of tools from this article can do another behavior, example
9.1. GitHub token ¶
Get your GitHub token and add environment variable with value — your token.
You need to select all repo scopes.
9.2. Upstream branch ¶
You need to set upstream branch:
git checkout yourbranch
git branch --set-upstream
- yourbranch — name of branch, which you want to do upstream. Please, change yourbranch to real branch name.
9.3. CHANGELOG.md ¶
Create blank file CHANGELOG.md. If no, generate-changelog will works incorrect.
9.4. package.json ¶
{
"name": "SashaSublime",
"version": "4.14.7",
"scripts": {
"release": "release-it"
}
}
- SashaSublime — name of your package,
- 4.14.7 — previous version of your package. Use 0.0.0, if you add first release for your package.
Replace SashaSublime and 4.14.7 to your real values.
9.5. .release-it.json ¶
{
"buildCommand": "changelog -f - -u https:\/\/${repo.host}\/${repo.repository} | tee messages\/${version}.txt | cat - CHANGELOG.md > temp && mv temp CHANGELOG.md && sed -i '\/\\\"install\\\": \\\"messages\\\/install\\.txt\\\"\/i\\\"${version}\\\": \\\"messages\\\/${version}\\.txt\\\",' messages.json && js-beautify -r messages.json",
"changelogCommand": "changelog -f -",
"github": {
"release": true,
"tokenRef": "TOKEN_GITHUB_FOR_RELEASE_IT"
},
"npm": {
"publish": false
},
"safeBump": false,
"src": {
"addUntrackedFiles": true,
"tagName": "st3-%s"
}
}
Hint
Pay attention to slashes escaping. To convert terminal command to JSON I recommend to use freeformatter.com service. For example:
sed -i '/\"install\"\: \"messages\/install\.txt\"/i\"4\.14\.7\"\: \"messages\/4\.14\.7\.txt\",' messages.json
will convert to:
sed -i '\/\\\"install\\\": \\\"messages\\\/install\\.txt\\\"\/i\\\"${version}\\\": \\\"messages\\\/${version}\\.txt\\\",' messages.json
9.6. messages.json ¶
{
"install": "messages/install.txt"
}
10. Usage ¶
Add, commit and push your changes to remote GitHub repository. Example:
# Make any changes
D:\SashaSublime>git add .
# I use commitizen instead of git commit
D:\SashaSublime>git cz
cz-cli@2.9.6, cz-conventional-changelog@1.2.0
Line 1 will be cropped at 100 characters. All other lines will be wrapped after 100 characters.
? Select the type of change that you're committing: build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
? Denote the scope of this change ($location, $browser, $compile, etc.):
release-it
? Write a short, imperative tense description of the change:
Fix .release-it.json
? Provide a longer description of the change:
Add to .release-it.json URL of SashaSublime repository
? List any breaking changes or issues closed by this change:
[SashaDevelop 52e517a] build(release-it): Fix .release-it.json
1 file changed, 2 insertions(+), 1 deletion(-)
D:\SashaSublime>git push
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 735 bytes | 183.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To https://github.com/Kristinita/SashaSublime.git
0360628..52e517a SashaDevelop -> SashaDevelop
Now run one of command:
- release-it -n -V or release-it patch -n -V — for release patch version;
- release-it --minor -n -V — for release minor version;
- release-it --major -n -V — for release major version;
- release-it 4.14.7 -n -V — for release custom version; 4.14.7 in example.
Also you can create pre-releases.
Example result see in demonstration section.
11. Details ¶
If you want to know, how files and commands works, please, read this section.
11.1. release-it command ¶
release-it -n -V
- -n — non-interactive mode. That you don’t need input values each time manually.
- -V — verbose. You can disable this command-line argument, but if you will get a bug, this argument may help you.
11.2. .release-it.json ¶
11.2.1. buildCommand ¶
- changelog -f - — generate changelog. “-” — argument, that changelog stdout to console,
-u https:\/\/${repo.host}\/${repo.repository}
— support URL's in changelog, that the user can quick go to the commit link.${repo.host}
— github.com.${repo.repository}
—<your username>/<your repository>
,Kristinita/SashaSublime
for my example.Example:
- if
-u https:\/\/${repo.host}\/${repo.repository}
, changelog generate([40783aee](https://github.com/Kristinita/SashaSublime/commit/40783aee5a678d62f4e703248c277c725246f1ea))
, - if no
-u https:\/\/${repo.host}\/${repo.repository}
, changelog generate(40783aee)
.
- if
tee messages\/${version}.txt
— output changelog to messages/<your new release>.txt file. File <your new release>.txt will create automatically. See description of tee command.cat - CHANGELOG.md > temp && mv temp CHANGELOG.md
— append changelog at beginning of CHANGELOG.md file. CHANGELOG.md do not overwrite.sed -i '\/\\\"install\\\": \\\"messages\\\/install\\.txt\\\"\/i\\\"${version}\\\": \\\"messages\\\/${version}\\.txt\\\",' messages.json
— add"<your version>": "messages/<your version>.txt",
line before"install": "messages/install.txt"
line.js-beautify -r messages.json
— beautify messages.json file in-place
11.2.2. Another lines ¶
- changelogCommand — command, that generate changelog to
https://github.com/<your username>/<your repository>/releases
. Command must stdout to console. "release": true,
— post changelog tohttps://github.com/<your username>/<your repository>/releases
.- TOKEN_GITHUB_FOR_RELEASE_IT — your TOKEN_GITHUB_FOR_RELEASE_IT environment variable,
"npm": {"publish": false},
— don’t publish release to npm. We are writing Sublime Text package, not npm modules, so needs this parameter."safeBump": false,
— that correct version inhttps://github.com/<your username>/<your repository>/releases
; see issue for details."addUntrackedFiles": true,
— add untracked file messages/<version>.txt to release commit."tagName": "st3-%s"
— correct tag name for Package Control. Tags for Sublime Text 3 must be in st3-<your version> format, for example — st3-4.14.7.
12. Problems and non-fixed bugs ¶
- You can’t use cz-emoji for commit generation. Changelog will blank.
- release-it can works incorrect in --dry-run mode.
- You can have bugs, if you want to use ${changelog} release-it variable.
13. Testing environment ¶
- Windows 10 Enterprise LTSB 64-bit EN,
- Node.js 9.4.0,
- git 2.16.0.windows.2,
- release-it 7.3.0,
- changelog 1.7.0,
- tee (GNU coreutils) 8.26, packaged by Cygwin (8.26-1),
- cat (GNU coreutils) 8.26, packaged by Cygwin (8.26-1),
- mv (GNU coreutils) 8.26, packaged by Cygwin (8.26-1),
- sed (GNU sed) 4.2.2,
- js-beautify 1.7.5.