tag-release
v10.0.3
Published
Automatically Tag and Release Repositories
Downloads
44
Keywords
Readme
tag-release
Installation
$ npm install -g tag-release
GitHub Personal Access Token
tag-release
requires a GitHub personal access token in order to execute certain GitHub commands.
In your root directory there should be a .tag-releaserc.json
file that contains your GitHub username and access token.
It should appear as following:
{
username: "myusername",
token: "token123"
}
You can create, open, and edit this file by running tag-release config
. Alternatively, you can simply run tag-release
and follow the
instructions provided if you don't already have one created.
In order to create your GitHub personal access token you will need to visit https://github.com/settings/tokens
and follow these steps:
- From the link provided, click
Generate new token
- Set a note to your preference, maybe something like
tag-release token
to make it easy to remember what the token is used for. - Set
Expiration
toNo expiration
. It will complain about how that is scary, but you can always come in after and remove the token. - Check the
workflow
scope. This should also check all items in therepo
scope as well. If it doesn't, please check them too. - Scroll to the bottom and click
Generate token
- Once successfully created, copy the token and enable SSO for the token if the repos you are working with require that.
- Once the token is copied, either manually update the
.tag-releaserc.json
file or re-run thetag-release
command you were running and enter when prompted if you didn't have a token before.
Note: Here is a GitHub link on how to create personal access tokens as well: https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token If you choose to follow these steps, please make sure the scope of your token is the same as described in the steps listed above.
Usage
Default
$ tag-release
You will be prompted for information regarding what type of release you are
making (major, minor, patch). Along the way, you'll have the opportunity to
verify, modify, or cancel the tag-release
process.
Commands
tag-release
supports many different commands and options. You can view a summary of these by providing the --help
option from the terminal.
Usage: tag-release [options] [command]
Options:
--verbose console additional information
--maxbuffer <n> overrides the max stdout buffer of the child process, size is 1024 * <n>
-V, --version output the version number
-h, --help output usage information
Commands:
continue continue from a previously conflicted state
config open the tag-release config in your default editor
dev [branch] create a PR from origin feature branch to upstream feature branch
pr [scope] update consumer project feature branch and create a PR to develop
prerelease|pre [identifier] create a pre-release
qa [scope] create initial upstream feature branch for consumer project
reset reset repo to upstream default and secondary branches
help [cmd] display help for [cmd]
Pre-releases
Pre-releases are mainly for interim releases that are not intended for production use. The benefit of this approach is being able to quickly deploy releases that can be easily iterated upon.
Note: When using the
prerelease
command you are required to have an upstream feature branch with the same name.
Usage:
$ tag-release prerelease
$ tag-release pre
$ tag-release prerelease foo
$ tag-release pre foo
Example:
$ tag-release prerelease
? Pre-release Identifier: foo
? What type of release is this (Use arrow keys)
❯ Pre-major (Breaking Change)
Pre-minor (New Feature)
Pre-patch (Bug Fix)
Pre-release (Bump existing Pre-release)
etc...
Using the optional option tag
will allow you to bypass the identifier step.
Example:
$ tag-release prerelease foo
? What type of release is this (Use arrow keys)
❯ Pre-major (Breaking Change)
Pre-minor (New Feature)
Pre-patch (Bug Fix)
Pre-release (Bump existing Pre-release)
etc...
These tags always match the following schema: [version]-[identifier].[bump]
| Latest Release | Latest Prerelease | Release | Pre-release | Identifier | Next Version | |----------------|-------------------|---------|---------------|---------------|----------------| | 1.2.3 | N/A | major | yes | pre (default) | 2.0.0-pre.0 | | 1.2.3 | 2.0.0-pre.0 | major | yes | pre (default) | 2.0.0-pre.1 | | 1.2.3 | 2.0.0-pre.1 | minor | no | N/A | 1.3.0 | | 1.3.0 | 2.0.0-pre.1 | minor | yes | filter | 1.4.0-filter.0 |
Pre-release Promotion
This command is used for promoting a pre-release created by tag-release
into an offical release
that is intended to be deployed to production.
Usage:
$ tag-release promote
Example:
$ tag-release promote
? Select the pre-release you wish to promote: (Use arrow keys)
> v1.1.1-blah.0
v2.0.0-another.1
v3.0.0-this.5
After selecting the tag you wish to promote it will attempt remove all pre-release commits from history
and rebase it with your default branch. If conflicts arise you will be prompted to fix the conflicts and then continue
with the promotion process by running tag-release continue
. This cycle will continue until all conflicts
are resolved and then it will continue as normal.
Using the optional option tag
will allow you to bypass the selection step.
Example:
$ tag-release promote v1.1.1-feature.2
$ tag-release promote 1.1.1-feature.2 # v is optional for tag
QA
This command is used to create an upstream feature branch in your consumer project that pulls in your dependency projects.
Its primary use is to pull in pre-releases that were previously created using tag-release prerelease
. It will give you the option to update package versions, ask for the reason you are making this change (typically this is
the theme of all changes for your work), and prompt you with a list of tags to choose from per package.
Usage:
my-consumer-project git:(develop) tag-release qa
Example:
my-consume-project git:(develop) tag-release qa
? Select the package(s) you wish to update: (Press <space> to select)
❯ ◯ my-dependency-project
◯ my-other-dependency-project
◯ my-last-dependency-project
? What is the reason for this change: This is my reason
? Update my-dependency-project from 1.2.3 to: (Use arrow keys)
❯ 2.0.0-test.0
1.2.4-bug.1
1.3.0-somechange.0
? What type of change is this work (Use arrow keys)
❯ feature
defect
rework
? What do you want your branch name to be? feature-reason
Note: The branch name that is created to hold your changes is based off of the first pre-release identifier from the package versions you are updating, but if there is no identifier it will use your "reason for this change" message but by removing some non-critical words. You will also have the ability to update this branch's name to your liking as well.
If you find yourself having to update a pre-release you created you can update your feature branch by running tag-release qa
again from the feature branch. It will pick up the packages you previously updated and give you the ability to update them to the new versions. This is based on the lastest commit being a bump commit in the follow format: Bumped [ package ] to [ version ]: [ reason ]
. If there are multiple package changes the format will be the following: Bumped [ package ] to [ version ], [ package ] to [ version ]: [ reason ]
If the default scope tag-release
uses is not fitting for your usage, you have the ability to provide your own.
Usage:
my-consumer-project git:(develop) tag-release qa myorg
Note:
qa
will use a default scope oflk
PR
This command is used to create a PR into your consumer project's develop branch.
It will read in the packages that you updated from your bump commit and ask you which version you wish to update them to. This is where you will pick offical releases and not pre-releases.
Note:
pr
should be run from your feature branch that was created usingqa
Usage:
my-consumer-project git:(my-feature-branch) tag-release pr
Example:
my-consumer-project git:(my-feature-branch) tag-release pr
? Update my-dependency-project from 1.2.3-identifier.1 to: (Use arrow keys)
❯ 2.0.0
1.3.0
1.2.4
1.2.3-identifier.1
Note:
pr
will automatically create the GitHub PR for you and add the appropriateReady to Merge into Develop
label
You can also provide a --no-bump
flag to the command and it will create a PR against your base branch
without the need of a bump commit.
tag-release
rc File and Environment Variables
tag-release
will attempt to read from the rc file .tag-releaserc.json
or the environment variables,
LKR_GITHUB_USER
and LKR_GITHUB_TOKEN
.
example rc file:
{
username: "[email protected]",
token: "token12345"
}
Where username
is your GitHub username and token
is your Github personal access token.
tag-release
as a Library
Usage
const tagRelease = require( "tag-release" );
tagRelease.run({release:'minor', cwd: "/path/to/repo" }).then(result=>{
console.log( "success", result);
}).catch(error=>{
console.log("failiure", error );
});
Note:
release
andcwd
are required
release
can be any of the following:
major
minor
patch
cwd
is the current working directory of the repository that tag-release
will run on.
Pre and Post Scripts
tag-release
supports the idea of pre
and post
scripts. In order to take advantage
of thie feature you will need to add a tag-release
section to your package.json
.
Usage
The following will create pre
and post
script hooks for the start
command of tag-release
.
"tag-release": {
"prestart": "node ./preStart.js",
"poststart": "node ./postStart.js"
}
As you can see from the example your script name will need to be pre
followed by the tag-release
command. For example, if I wanted to hook into the dev
command
my script names would be predev
and postdev
.
Here is a chart of all the commands tag-release
offers:
start
dev
pr
prerelease
promote
qa
reset
Note: You will need to use the full name of the command, not just an alias. For instance, you couldn't do
prepro
. Instead, it would beprepromote
.
Release Workflow
- Fork the dependency project & add development updates to your project.
Note: An example would be forking my-dependency-project and developing a feature based off its default branch. Your local branch should start with feature, defect, or rework (ex: feature-amazing-thing).
- Make a GitHub PR for your dependency project against an upstream branch.
my-dependency-project git:(my-feature-branch) tag-release dev
- After PR review is approved, pre-release your dependency project.
my-dependency-project git:(my-feature-branch) tag-release prerelease new-feature
Note: This will create a pre-release that will be published to npm (sinopia) and GitHub (ex: 1.2.3-new-feature.0)
- Create a consumer project upstream branch to include your pre-released dependency project for QA.
my-consumer-project git:(main) tag-release qa
Note: This will create an upstream feature branch on the consumer project.
Deploy your consumer project's branch to a QA test environment.
Once QA has passed your code, promote dependency project's pre-release to an offical release.
my-dependency-project git:(main) tag-release promote
Note: This will change your pre-release from something like 1.2.3-new-feature.0 to 1.2.3 or whatever version is next in line. You will use this version in the next step.
- Update your consumer project's branch to use the real dependency project's version and create a GitHub PR for the AEs to merge into develop.
my-consumer-project git:(my-feature-branch) tag-release pr
Note:
tag-release
will auto-create the GitHub PR for you and add the appropriateReady to Merge into Develop
label.
Frequently Asked Questions
Note: Click the following items to reveal more information