make-pkg v0.8.0
Contents
- make-pkg — initialize and maintain npm package projects
- Package initialization (scaffolding)
- Package release and maintenance
- Supported platforms
- Installation
- Usage
- License
- Changelog
make-pkg — initialize and maintain npm package projects
make-pkg
is a Unix CLI for initializing npm package projects and implementing a release and maintenance workflow.
The projects initialized are backed by a local Git repository with a remote GitHub counterpart.
While the typical use case is to create npm packages, make-pkg
can be used to manage GitHub-based OSS projects in general.
make-pkg
is opinionated, which allows it to simplify and automate many tasks.
For instance, make-pkg
is managed by itself, and this read-me was scaffolded by it and is also kept up-to-date by it on every release.
Package initialization (scaffolding)
- Initializes the
package.json
package-description file through a series of prompts, with configurable defaults, similar to, but more fully-featured thannpm init
. - Initializes a local Git repository and the
.gitignore
file. - Creates a corresponding remote repository on GitHub and links the local repository to it.
- Instantiates templates for various standard files:
README.md
,LICENSE.md
,CHANGELOG.md
- Creates stubs for the main module file and/or CLIs.
- Creates stubs for tests, plus a few standard tests for CLIs.
- For packages intended for publication in the npm registry, adds an npm-version badge and license badge, courtesy of shields.io.
- Installs a
Makefile
that implements a set of tasks for releasing and ongoing package maintenance, along with supporting development-dependency packages (which are the same as or a subset of the ones for this utility - see npm dependencies)
Package release and maintenance
Note that make-pkg
itself is no longer in the picture after having initialized a package project; instead, ongoing tasks are invoked through the standard make
utility.
These tasks are defined in file Makefile
, which can be customized after the fact, if needed; make list
lists all top-level tasks.
make version
andmake verinfo
update and list the package's version number, respectively:make verinfo
lists the current version number frompackage.json
as well as the most recently assigned Git version tag; the Git tag is assumed to be in sync with the latest version published in the npm registry, if applicable; thepackage.json
version may be ahead, in preparation for a new release.make version [VER=<new-ver>]
updates the package version number inpackage.json
and, if present, in source files: IfVER
is not specified, the new version number is prompted for. The new version number is validated, including to prevent accidental lowering of the version number; however, in exceptional situations you may specifyFORCE=1
on the command line to override. Updates the version number inpackage.json
. Updates the version number in source files in the./bin
and./lib
subfolders, using string replacement to updatev<major>.<minor>.<patch>
instances of the old version number.<new-ver>
can either be an explicit<major>.<minor>.<patch>
version specifier or specify how to increment* the current version number via the component to increment:patch
,minor
,major
,prepatch
,preminor
,premajor
, orprerelease
; using apre
-prefixed specifier on a non-pre-release version number appends-0
to it.
make update-readme
updates fileREADME.md
to act as a single source of all relevant, current project information- Pulls in the then-current contents of the
LICENSE.md
andCHANGELOG.md
files. - If needed, updates the calendar year in
LICENSE.md
. - If applicable, pulls in usage information output by the project's CLI.
- By default, adds an auto-generated, auto-updating TOC (table of contents) at the top, courtesy of doctoc; see below for how to turn that off.
- Lists the project's dependencies with links to their respective homepages.
- Pulls in the then-current contents of the
make toggle-toc
turns inclusion of an auto-generated, auto-updating TOC inREADME.md
on or off.- Shows the current TOC inclusion status and prompts to toggle it; by default, inclusion of a TOC is turned on.
- To change the TOC title, modify property
net_same2u.make_pkg.tocTitle
in filepackage.json
. - To change the TOC settings for future projects, run
make-pkg -e
and edit thevTOC_*
settings. - To update the TOC on demand (generally not necessary), run
make update-toc
.
make toggle-man
turns generating a man page for a package's CLI on or off.- Shows whether the feature is currently on and prompts to toggle it; by default, it is turned off.
- To turn the feature on or off for future CLI projects, run
make-pkg -e
and edit thevMAN_ON
setting. - To update the man page on demand, run
make update-man
; updating is performed automatically duringmake release
. - To update and view the man page locally, run
make view-man
. - Note: For this feature to work, a package's CLI must exhibit very specific behavior: when invoked with
--man-source
, it must output a Markdown-formatted document that marked-man can process; the Markdown document is extracted as-is to./doc/
, and the man-page-format (ROFF) document created bymarked-man
is saved to./man/
. Aman
property inpackage.json
points to the ROFF document, which, in the case of global installation (-g
) of the package, causesnpm
to install the ROFF document as a system-wide man page (except on Windows).make-pkg
itself uses the feature, so you can look at its CLI and package.json file to see how it's implemented.
make test
runs tests:make release
integrates all of the above tasks to publish a release; if any sub-task fails, the overall task is aborted:- Ensures that the active branch is
master
and that there are no untracked files. - If the
package.json
version number is already ahead of the latest Git version tag, that version number is offered as the new release's version number by default, but you can opt to change it. If you do, or if the package version number is not ahead, you're prompted for the new version number as described formake version
above. - Runs the tests, as described above;
NOTEST=1
can be appended to themake release
invocation to skip tests. - Adds a date-stamped section for the new version at the beginning of
CHANGELOG.md
and opens it for editing to describe what's changed in the new release. - If applicable and turned on, creates or updates the man page for the project's (main) CLI in
./man
using marked-man - seemake toggle-man
above. - Updates
README.md
as described above, opens it in the system's text editor for final review, and prompts for continuing on closing it. - Commits, using the new changelog section as the commit message.
- Creates an annotated Git version tag with the new version number; also (re)creates the lightweight 'stable' tag to mark the most recent stable version, or, analogously, the 'pre' tag for pre-release versions.
- Pushes the changes and tags to the
master
branch of the remoteorigin
GitHub repository. - Unless the project is marked as private in
package.json
, offers to publish the new version to the npm registry.- Pre-release versions are published with
--tag pre
, so as to make the latest pre-release version installable on demand withnpm install <pgk>@pre
, while retaining the most recent release version as the default version.
- Pre-release versions are published with
- Ensures that the active branch is
make push
pushes changes to the remoteorigin
repository:- Initiates a commit, if necessary, but aborts if there are untracked files.
- On successful commit, pushes changes to the branch of the same name in the remote
origin
repository - without tags, however.
make browse
andmake browse-npm
open the project's GitHub repository and the package's page in the npm registry, respectively, in the default web browser.
Supported platforms
Linux and OS X
In principle, any Unix-like platform with bash
and GNU make
and otherwise either GNU or BSD utilities.
Additional prerequisites
npm
- as part of a Node.js or io.js installation- if publishing to the npm registry is desired, an account there
git
, a distributed version-control system- a GitHub account
Note that bash
is required both for running make-pkg
itself initially and
later for running the shell commands in Makefile
via make
from inside the
projects generated.
Installation
With Node.js or io.js installed, install from the npm registry:
[sudo] npm install -g make-pkg
Note:
- Whether you need
sudo
depends on how you installed Node.js / io.js and whether you've changed permissions later; if you get anEACCES
error, try again withsudo
. - The
-g
ensures global installation and is needed to putmake-pkg
in your system's$PATH
.
Usage
Example
The following image shows an example interaction with the series of prompts presented during package initialization:
Initializing a new package
- Create a directory for the new package project.
cd
to it.- Run
make-pkg [<pkg-type>]
- Experimental
<pkg-type>
allows creating a specific type of package:- Specifying a type streamlines the initialization process by skipping certain prompts and assuming appropriate default values.
- Additionally, type-specific prompts may be presented, and the resulting package may have additional features and/or a different internal structure.
- Conversely, not specifying a type provides the most flexibility for creating a package that contains a JS library and/or a CLI.
- Types currently supported are:
- Refer to the docs for details.
- On first use you'll be prompted to specify required global settings and defaults, such as your GitHub username, your website, and your preferred OSS license.
- To modify settings later, run
make-pkg -e
from any directory.
- To modify settings later, run
- You'll be guided through a series of prompts to create the
package.json
file. On confirming the intent to create the
package.json
file as presented, the remaining tasks - creating the repositories, instantiating templates, creating stubs - run automatically.
- Experimental
To-dos after the project has been initialized:
- Flesh out the stub module (in
./lib
) and/or the CLI stub (in./bin
) with the actual implementation.- Note: The specific to-dos may differ for special package types.
- Flesh out the stub tests in
./test
. - Flesh out
README.md
, making sure to replace instances of "???", the missing-information placeholder. - Use the
make
tasks as described above for releasing and ongoing maintenance.
Command-line syntax
Find concise usage information below; for more detailed information, read the manual online, or, once installed, run man make-pkg
.
$ make-pkg --help
Initializes an npm-package project in the current directory and
implements a maintenance and release workflow.
make-pkg [-l] [-f] [<pkg-type>]
make-pkg -e
-l suppresses creation of remote repo on GitHub
-f forces running in a non-empty directory
-e opens the settings file for editing
<pkg-type> [experimental] creates a specific package type:
'lib': JS library (only)
'cli': CLI (only), global installation preferred
'awf': an Alfred 2 workflow
Standard options: --help, --man, --version, --home
License
Copyright (c) 2015-2016 Michael Klement mklement0@gmail.com (http://same2u.net), released under the MIT license.
Acknowledgements
This project gratefully depends on the following open-source components, according to the terms of their respective licenses.
npm dependencies below have an optional suffix denoting the type of dependency: the absence of a suffix denotes a required run-time dependency; (D)
denotes a development-time-only dependency, (O)
an optional dependency, and (P)
a peer dependency.
npm dependencies
Changelog
Versioning loosely complies with semantic versioning (semver). Since this utility is applied only once to a given package - in order to initialize it - maintaining compatibility is less important. However, larger changes will be reflected in higher version-number increases.
v0.8.0 (2016-04-21):
- enhancement, behavioral change
make push
no longer tries to push tags to the server, so as to allow quick pushing of changes without running into errors when trying to redefine tags.
- enhancement, behavioral change
v0.7.2 (2016-04-21):
- fix Makefile template: npm registry saved-credentials detection code
updated to account for how newer npm versions save them
(
//registry.npmjs.org/:_authToken=
).
- fix Makefile template: npm registry saved-credentials detection code
updated to account for how newer npm versions save them
(
v0.7.1 (2015-11-08):
- doc Tweaks to the read-me templates.
v0.7.0 (2015-11-08):
- behavioral change The package's directory name is now invariably used as the npm package name.
- enhancement A package name is now checked for being a legal npm-registry package name: if not, a warning is given at the first prompt, and, unless a private package is being created, initialization will abort.
- enhancement, experimental Support for package types added, both to streamline regular package initialization and to add support for specialized packages such as Alfred 2 workflows.
v0.6.3 (2015-10-28):
- enhancement An attempt to run tests now bows out gracefully with a status
messsage (and without error) if the
./test
subdir. is empty (save for hidden items), before attempting to invoketap
orurchin
.
- enhancement An attempt to run tests now bows out gracefully with a status
messsage (and without error) if the
v0.6.2 (2015-10-28):
- enhancement
README.md
: Added custom badge that marks a project initially as not ready for release; to be removed when appropriat later; similarly, for npm-package projects, the npm-version badge is now initially commented out, to be uncommented once the project is published to the npm registry.
Streamlined the license badges to always use a custom badge with the license's SPDX ID, which also makes it work with npm-package projects not yet published to the registry. - dev Makefile robustness improved.
- enhancement
v0.6.1 (2015-09-15):
- enhancement New Makefile task
make view-man
updates the man page and views it locally withman
. - fix Outdated status message at the end of package initialization corrected.
- doc Read-me and man-page improvements.
- enhancement New Makefile task
v0.6.0 (2015-09-15):
- enhancement New feature: optional, off-by-default support for creating and installing a man page
for a package's main CLI - see description of the
make toggle-man
Makefile task in file README.md. - behavioral change Makefile task
toc
renamed totoggle-doc
; also, toggling no longer attempts to remove an existing TOC on turning off, and no longer automatically adds one on turning on. - fix
make release
now once again adds the version-specific changelog entries to the Git commit message. - doc
make-pkg
now comes with a man page;make-pkg -h
now just outputs concise usage info.
- enhancement New feature: optional, off-by-default support for creating and installing a man page
for a package's main CLI - see description of the
v0.5.6 (2015-09-14):
- fix A preconfigured
.gitignore
file is now copied to a new package folder, as it always should have been.
- fix A preconfigured
v0.5.5 (2015-08-03):
- fix Read-me template now uses
```nohighlight
to fence CLI usage output, which is what themake update-readme
andmake release
tasks expect.
- fix Read-me template now uses
v0.5.4 (2015-07-08):
- enhancement Read-me template improved so as to ensure that CLI usage information is printed without syntax highlighting.
v0.5.3 (2015-06-29):
- enhancement Test stub improved.
v0.5.2 (2015-06-29):
- enhancement CLI and main-module templates improved.
v0.5.1 (2015-06-22):
- enhancement CLI test template for unknown options added; existing templates improved.
v0.5.0 (2015-06-16):
- change Pre-release npm tag changed to fixed string 'pre' so as to have that track the most recent pre-release.
- change Pre-release Git tag analogously changed to 'pre'.
- fix
README.md
template is now again correctly expanded in Bash 4.x. - enhancement New test for test prerequisites added.
- dev Tests improved to detect corrupt of
README.md
template on expansion.
v0.4.0 (2015-06-16):
- new Consistent support for pre-release versions added.
- enhancement New CLI test template added for testing behavior with unknown options.
- fix Minor bug in CLI test templates fixed.
v0.3.5 (2015-06-13):
- enhancement When initializing a CLI package, supported-platform information is now added to the installation chapter in the read-me file.
- enhancement
make release
now also opensREADME.md
for editing, so as to give you a chance for a final review, and prompts for continuing after. - enhancement
make release
now aborts if the missing-information placeholder '???' is found inREADME.md
.
v0.3.4 (2015-06-06):
- new License badge added to
README.md
template for non-npm packages, based on shields.io.
- new License badge added to
v0.3.3 (2015-06-03):
- doc Read-me updated to reflect current implementation (badges,
make browse-npm
).
- doc Read-me updated to reflect current implementation (badges,
v0.3.2 (2015-06-03):
- new npm-license badge added to
README.md
template for npm packages, based on shields.io. - change npm-version badge in
README.md
template for npm packages switched from badge.fury.io to shields.io, because the latter seems like a one-stop source for multiple badges. - enhancement Small Makefile tweaks.
- new npm-license badge added to
v0.3.1 (2015-06-03):
- enhancement Generated
CHANGELOG.md
files now have version numbers hyperlinked to GitHub for comparing each release to the previous one. - fix Removed obsolete check from Makefile.
- enhancement Generated
v0.3.0 (2015-06-03):
- enhancement Improvements to the versioning workflow: new
make verinfo
task only lists version numbers, whereasmake version
now always updates - either by specifyingVER=...
on the command line, or by prompting the user. - enhancement TOC placement in generated
README.md
files changed to ensure that badges stay at the top. - fix npm-registry-installation TOC entry in template for
README.md
fixed, along with corresponding chapter.
- enhancement Improvements to the versioning workflow: new
v0.2.3 (2015-06-02):
- fix, enhancement CLI installation instructions in read-me template fixed & improved.
- enhancement Error-reporting helper function added to CLI test stubs.
- doc Amended this read-me.
v0.2.2 (2015-06-01):
- new
make browse
opens the project's GitHub repository in the default browser. - enhancement npm-registry installation instructions in generated
README.md
files improved. - doc npm-registry installation instructions in
README.md
improved.
- new
v0.2.1 (2015-05-31):
- new For packages intended for publication in the npm registry, adds an npm version badge.
- fix Typo in
templates/README.tmpl.md
.
v0.2.0 (2015-05-31):
v0.1.0 (2015-05-31):
- Initial release.
8 years ago
8 years ago
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago