npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

foundry

v4.7.0

Published

Release manager for npm, bower, component, PyPI, git tags, and any plugin you can write

Downloads

621

Readme

foundry Build status Build status

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

Example foundry-release

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 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#environment

Documentation

Release process

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)

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 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 customCommand

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"
{
  "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 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
{
  "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:

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.