Release manager for npm, bower, component, PyPI, git tags, and any command you want.
This was created out of frustration; there was no generic sharable release manager.
Features:
- Well tested release library with well tested commands
- Specification is CLI based, allowing for any language implementation
- Transparent output; always know what commands are being executed
- Cross platform support (GNU/Linux, OS X, Windows)
- Resumable releases via
foundry resume
- Allows for human and machine error (e.g. forget to log in, repository is being flaky)
- Newsletter, subscribe to hear about new features and releases
Install the module via: npm install foundry
By default, foundry
is not configured with any release commands. Install a release command via npm
:
npm install foundry-release-bower # bower
npm install foundry-release-component # component.io
npm install foundry-release-git # git
npm install foundry-release-npm # npm
npm install foundry-release-pypi # PyPI
Details about existing commands and their documentation can be found under the Commands heading.
For example purposes, we will create/release on a local-only git
repository.
# Create git repo
mkdir foundry-example
cd foundry-example
git init
echo "Hello World" > README.md
git add README.md
git commit -m "Added documentation"
# Generate `package.json` with `foundry` config
cat > package.json <<EOF
{
"foundry": {
"releaseCommands": [
"foundry-release-git"
]
}
}
EOF
# Install corresponding `git` foundry-release command
npm install foundry-release-git
# Run our release (links repeated at bottom of example)
# Prepending `./node_modules/.bin/` to `PATH` can be avoided by using `foundry.cli`
# https://github.com/twolfson/foundry.cli
# or by using `npm-run-script`
# https://www.npmjs.org/doc/misc/npm-scripts.html#environment
PATH="$PATH:$PWD/node_modules/.bin/"
foundry release 1.0.0
# Configuring steps with FOUNDRY_VERSION: 1.0.0
# Configuring steps with FOUNDRY_MESSAGE: Release 1.0.0
# Running step: foundry-release-git update-files "$FOUNDRY_VERSION" "$FOUNDRY_MESSAGE"
# Running step: foundry-release-git commit "$FOUNDRY_VERSION" "$FOUNDRY_MESSAGE"
# [master ec7a32d] Release 1.0.0
# Running step: foundry-release-git register "$FOUNDRY_VERSION" "$FOUNDRY_MESSAGE"
# Running step: foundry-release-git publish "$FOUNDRY_VERSION" "$FOUNDRY_MESSAGE"
# Pushes to remote server
# See the release commit and tag
git log --decorate --oneline
# c6ce921 (HEAD, tag: 1.0.0, master) Release 1.0.0
# f0c25b3 Added documentation
Links to alternatives to extending PATH
:
foundry.cli
, global CLI bindings forfoundry
npm-run-script
, run scripts from withinnpm's
context
When a release occurs, the following steps are processed:
- Update files, update package files with the new version and changes (e.g. update
package.json
, add toCHANGELOG.md
) - Commit, persist any changes to a version control system (e.g.
git commit && git tag
) - Register, if the package is new (semver ===
1.0.0
), then register it to its repository (e.g.python setup.py register
)- We can customize this semver via the
registerVersion
configuration
- We can customize this semver via the
- Publish, release changes to package's repository (e.g.
npm publish
)
foundry
can be configured via a JSON .foundryrc
file or under a foundry
key in a package.json
. In both cases, we expect the JSON to be the same.
- registerVersion
String
- Semver to identify a new package by (e.g.0.1.0
,1.0.0
)- When the
release
semver matches this, we will runregister
steps. Otherwise, we won't. - By default,
registerVersion
is1.0.0
- We have chosen this to avoid the confusion of allowing "minor" releases in
0.x.y
that introduce breaking changes
- We have chosen this to avoid the confusion of allowing "minor" releases in
- When the
- releaseCommands
Array
- Collection of commands to use when releasing-
String|Object
- Information about command to run when releasing- A string is shorthand for
{type: releaseCommand, command: {{string}}}
- Objects have a required
type
property that changes their behavior- type
String
- Classification of command- This can be
releaseCommand
orcustomCommand
- This can be
- type
- A string is shorthand for
-
releaseCommand is a CLI command that lines up with foundry-release-spec
- type
String
- Classification of command - command
String
- Name of command to use- During
release
, we will each of the release steps (e.g.{{command}} update-files FOUNDRY_VERSION FOUNDRY_MESSAGE
) - For example, this would be
foundry-release-git update-files 1.0.0 "Release 1.0.0"
- During
{
"type": "releaseCommand",
"command": "foundry-release-git"
}
customCommand is a command with a custom setup
- type
String
- Classification of command - updateFiles
String
- Script to run when updating files- This will be invoked via
sh
orcmd
depending on our OS - We provide
FOUNDRY_VERSION
andFOUNDRY_MESSAGE
via environment variables - An example command is
echo "$FOUNDRY_VERSION: $FOUNDRY_MESSAGE" >> CHANGELOG.md
- This is converted into
echo "1.0.0: Release 1.0.0" >> CHANGELOG.md
viash
- This is converted into
- A more practical command would be
npm run build
to compile pre-release assets
- This will be invoked via
- commit
String
- Script to run when committing changes to files- This is invoked in the same fashion as
updateFiles
withsh/cmd
and environment variables
- This is invoked in the same fashion as
- register
String
- Script to run when registering a package- This is only runs if registration requisite is met
- This is invoked in the same fashion as
updateFiles
withsh/cmd
and environment variables
- publish
String
- Script to run when publishing a package- This is invoked in the same fashion as
updateFiles
withsh/cmd
and environment variables
- This is invoked in the same fashion as
{
"type": "customCommand",
"updateFiles": "echo \"$FOUNDRY_VERSION\" > VERSION.txt"
}
Example config with all variations:
// This is for a `.foundryrc`
// In a `package.json`, we would be nested inside of the `foundry` key
{
"releaseCommands": [
"foundry-release-git", // Shorthand
{
"type": "releaseCommand",
"command": "foundry-release-npm"
},
{
"type": "customCommand",
"updateFiles": "echo \"$FOUNDRY_VERSION\" > VERSION.txt"
}
]
}
foundry
provides a command line interface for releasing.
$ foundry --help
Usage: foundry [options] [command]
Commands:
release [options] <version> Update package metadata and publish to registries
resume [options] Resume an incomplete release
commands List commands used by current package
completion Get potential completions for a command. Looks for `COMP_CWORD`, `COMP_LINE`, `COMP_POINT`.
Options:
-h, --help output usage information
-V, --version output the version number
Example releases are:
foundry release 1.0.0
foundry release 1.1.0
foundry release 2.0.0
Commands that automatically increment semver are planned (e.g.
foundry release major
,foundry release minor
). See #16 for more information.
foundry
release commands contain the foundry-release
keyword and adhered to the foundry
release command specification:
https://github.com/twolfson/foundry-release-spec
Existing commands are:
- foundry-release-bower, manages
version
inbower.json
- foundry-release-component, manages
version
incomponent.json
- foundry-release-git, runs
git tag
andgit commit
upon release - foundry-release-npm, manages
version
inpackage.json
and runsnpm publish
upon release - foundry-release-pypi, manages
version
insetup.py
and registers/zips/gzips package upon release - More commands can be found at https://www.npmjs.org/browse/keyword/foundry-release
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint
and test via npm test
.
Support this project and others by twolfson via donations.
http://twolfson.com/support-me
As of Dec 07 2013, Todd Wolfson has released this repository and its contents to the public domain.
It has been released under the UNLICENSE.