Fastest way to add new version of your Sublime Text package

1. Overview
2. Audience
3. Relevance
4. Motivation
5. Demonstration
6. Features
7. Limitations
8. Installation
9. Activation
   1. GitHub token
   2. Upstream branch
   3. CHANGELOG.md
   4. package.json
   5. .release-it.json
   6. messages.json
10. Usage
11. Details
    1. release-it command
    2. .release-it.json
       1. buildCommand
       2. Another lines
12. Problems and non-fixed bugs
13. 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:

1. Add changelog to GitHub release page,
2. Update CHANGELOG.md,
3. Update version in messages.json,
4. 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

Result: 1, 2.

CHANGELOG.md and messages.json:

messages/<version>.txt and package.json:

Releases page:

If you want to have same behavior, read on.

6. Features ¶

Tutorial of this article must be support:

1. cross-platform,
2. Semver major, minor, patch and custom tags.

7. Limitations ¶

1. 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.
2. Your commits must be must be compatible with Conventional Commits. List of supported scopes. I recommend use commitizen.

8. Installation ¶

You need to install:

1. Node.js and npm, if no;
2. git if no, even if you use another VCS;
3. 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;
4. release-it globally ≥ 7.3.0;
5. generate-changelog globally;
6. 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.

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"
	}
}

sed -i '/\"install\"\: \"messages\/install\.txt\"/i\"4\.14\.7\"\: \"messages\/4\.14\.7\.txt\",' messages.json

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).

• 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 to https://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 in https://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 ¶

1. You can’t use cz-emoji for commit generation. Changelog will blank.
2. release-it can works incorrect in --dry-run mode.
3. You can have bugs, if you want to use ${changelog} release-it variable.

13. Testing environment ¶

1. Windows 10 Enterprise LTSB 64-bit EN,
2. Node.js 9.4.0,
3. git 2.16.0.windows.2,
4. release-it 7.3.0,
5. changelog 1.7.0,
6. tee (GNU coreutils) 8.26, packaged by Cygwin (8.26-1),
7. cat (GNU coreutils) 8.26, packaged by Cygwin (8.26-1),
8. mv (GNU coreutils) 8.26, packaged by Cygwin (8.26-1),
9. sed (GNU sed) 4.2.2,
10. js-beautify 1.7.5.