twolfsonfoundry 
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
Getting Started
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 # PyPIDetails 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 documentationLinks to alternatives to extending PATH:
foundry.cli, global CLI bindings forfoundrynpm-run-script, run scripts from withinnpm'scontext
Documentation
Release process
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
registerVersionconfiguration
- We can customize this semver via the
- Publish, release changes to package's repository (e.g.
npm publish)
Configuration
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
releasesemver matches this, we will runregistersteps. Otherwise, we won't. - By default,
registerVersionis1.0.0- We have chosen this to avoid the confusion of allowing "minor" releases in
0.x.ythat 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 releasingString|Object- Information about command to run when releasing- A string is shorthand for
{type: releaseCommand, command: {{string}}} - Objects have a required
typeproperty that changes their behavior- type
String- Classification of command- This can be
releaseCommandorcustomCommand
- 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
shorcmddepending on our OS - We provide
FOUNDRY_VERSIONandFOUNDRY_MESSAGEvia 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.mdviash
- This is converted into
- A more practical command would be
npm run buildto 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
updateFileswithsh/cmdand 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
updateFileswithsh/cmdand environment variables
- publish
String- Script to run when publishing a package- This is invoked in the same fashion as
updateFileswithsh/cmdand 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"
}
]
}CLI
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.0Commands that automatically increment semver are planned (e.g.
foundry release major,foundry release minor). See https://github.com/twolfson/foundry/issues/16 for more information.
Commands
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
versioninbower.json - foundry-release-component, manages
versionincomponent.json - foundry-release-git, runs
git tagandgit commitupon release - foundry-release-npm, manages
versioninpackage.jsonand runsnpm publishupon release - foundry-release-pypi, manages
versioninsetup.pyand registers/zips/gzips package upon release - More commands can be found at https://www.npmjs.org/browse/keyword/foundry-release
Contributing
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.
Donating
Support this project and others by twolfson via donations.
http://twolfson.com/support-me
Unlicense
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.