Fastest way to add new version of your Sublime Text package

Page loading, please, little wait
Version 0.3.0
Posted —
Last modified —
  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 only 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/&lt;version&gt;.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

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

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": "GITHUB_TOKEN"
	},
	"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
[email protected], [email protected]


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:

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

11.2. .release-it.json

11.2.1. buildCommand

11.2.2. Another lines

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