Release manager for npm, bower, component, PyPI, git tags, and any plugin you can write
npm install foundryRelease manager for [npm][], [bower][], [component][], [PyPI][], [git tags][], and any command you want.
[npm]: http://npmjs.org/
[bower]: http://bower.io/
[component]: http://component.io/
[PyPI]: http://pypi.python.org/
[git tags]: http://git-scm.com/
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
[Newsletter]: http://eepurl.com/bCWbGj
npm install foundryBy default, foundry is not configured with any release commands. Install a release command via npm:
``bash`
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.
`bashCreate git repo
mkdir foundry-example
cd foundry-example
git init
echo "Hello World" > README.md
git add README.md
git commit -m "Added documentation"
with foundry config foundry-release command to PATH can be avoided by using foundry.cliLinks to alternatives to extending
PATH:-
foundry.cli, global CLI bindings for foundry
- https://github.com/twolfson/foundry.cli
- npm-run-script, run scripts from within npm's context
- https://www.npmjs.org/doc/misc/npm-scripts.html#environmentDocumentation
$3
When a release occurs, the following steps are processed:1. Update files, update package files with the new version and changes (e.g. update
package.json, add to CHANGELOG.md)
2. Commit, persist any changes to a version control system (e.g. git commit && git tag)
3. 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
4. Publish, release changes to package's repository (e.g. npm publish)$3
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 run register steps. Otherwise, we won't.
- By default, registerVersion is 1.0.0
- We have chosen this to avoid the confusion of allowing "minor" releases in 0.x.y that introduce breaking changes
- 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 or customCommandreleaseCommand 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"`js
{
"type": "releaseCommand",
"command": "foundry-release-git"
}
`[foundry-release-spec]: https://github.com/twolfson/foundry-release-spec
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 or cmd depending on our OS
- We provide FOUNDRY_VERSION and FOUNDRY_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 via sh
- A more practical command would be npm run build to compile pre-release assets
- commit String - Script to run when committing changes to files
- This is invoked in the same fashion as updateFiles with sh/cmd and environment variables
- 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 with sh/cmd and environment variables
- publish String - Script to run when publishing a package
- This is invoked in the same fashion as updateFiles with sh/cmd and environment variables`js
{
"type": "customCommand",
"updateFiles": "echo \"$FOUNDRY_VERSION\" > VERSION.txt"
}
`Example config with all variations:
`js
// 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"
}
]
}
`
$3
foundry provides a command line interface for releasing.`bash
$ foundry --help Usage: foundry [options] [command]
Commands:
release [options] 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:
`bash
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.$3
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 in bower.json
- [foundry-release-component][], manages version in component.json
- [foundry-release-git][], runs git tag and git commit upon release
- [foundry-release-npm][], manages version in package.json and runs npm publish upon release
- [foundry-release-pypi][], manages version in setup.py and registers/zips/gzips package upon release
- More commands can be found at https://www.npmjs.org/browse/keyword/foundry-release[foundry-release-bower]: https://github.com/twolfson/foundry-release-bower
[foundry-release-component]: https://github.com/twolfson/foundry-release-component
[foundry-release-git]: https://github.com/twolfson/foundry-release-git
[foundry-release-npm]: https://github.com/twolfson/foundry-release-npm
[foundry-release-pypi]: https://github.com/twolfson/foundry-release-pypi
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`.[twolfson-projects]: http://twolfson.com/projects
[twolfson-support-me]: http://twolfson.com/support-me
It has been released under the [UNLICENSE][].
[UNLICENSE]: UNLICENSE