foundry
v4.7.0
Published
Release manager for npm, bower, component, PyPI, git tags, and any plugin you can write
Downloads
634
Maintainers
Readme
foundry
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
- https://github.com/twolfson/foundry-release-spec
- 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
- http://eepurl.com/bCWbGj
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 # 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
- https://github.com/twolfson/foundry.cli
npm-run-script
, run scripts from withinnpm's
context- https://www.npmjs.org/doc/misc/npm-scripts.html#environment
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
registerVersion
configuration
- 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
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 releasingString|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"
}
]
}
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.0
Commands 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
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
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.