Fastest way to add new version of your Sublime Text package

Page loading, please, little wait
Version 0.3.0
Posted — 2018-01-23T10:43:14+0300
Last modified — 2019-08-02T19:06:59+0300
  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:

*CHANGELOG.md* and *messages.json*

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

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

Releases page:

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.

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.

GitHub token

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
  • -nnon-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.mdappend changelog at beginning of CHANGELOG.md file. CHANGELOG.md do not overwrite.
  • sed -i '\/\\\"install\\\": \\\"messages\\\/install\\.txt\\\"\/i\\\"${version}\\\": \\\"messages\\\/${version}\\.txt\\\",' messages.jsonadd "<your version>": "messages/<your version>.txt", line before "install": "messages/install.txt" line.
  • js-beautify -r messages.jsonbeautify 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

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