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 — 2022-09-08T20:02:40+0300
You can comment this web-page

Possibly outdated data

I wrote this article in January 2018. Some information from it may be out of date.

June 6 2021

  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.

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

  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.

Share

You can share this page on social networks using the AddToAny social buttons widget on the side of the page

Subcsribe

You can subscribe to the Atom or RSS feeds of all site materials and any of its categories and tags. To subscribe, you need to install any feed reader software. Choose subscriptions to Atom if preferable for you reading articles in your feed reader. Choose subscriptions to RSS feeds if more convenient for you to fully read articles in the browser; your feed reader will display solely the article abstracts.

Report a typo or error

(Solely for desktop, not mobile devices). If you see a typo, inaccuracy or error on this page, please report it using typo-reporter: select text with a typo/mistake → press Ctrl+Enter (⌘Enter for Mac) → write your comment → Send.

Edit page

You can edit this page yourself on GitHub and send pull request.

Comment

For any questions please contact via utterances comment widget below. Please be polite and constructive.

To leave a comment, you need to be registered with GitHub. When writing comments, use Markdown syntax.

Once sended, your comment should appear at the top of the list of issues for this site. Notification of a reply to your comment should be sent to the email associated with your GitHub account.

You can also write and send your message use GitHub Issues directly.

Работайте над собой