adhocore/pleasePublic

NotificationsYou must be signed in to change notification settings
Fork6
Star86

please is semver release made easy, detects current version from API or tags and next version from commits, creates detailed changelogs that are configurable.

License

MIT license

86 stars 6 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 213 Commits
.github		.github
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
please		please
please.json		please.json

Repository files navigation

adhocore/please

please (akaphp release or even npm release) is very simple Github+NPM release for~~PHP and/or Nodejs projects~~ anything.

Assumes you like semantic versioning of the format<major>.<minor>.<patch> and you have the commits are followingangular format!More on this formathere.

Actually you can release any thing not just PHP/Nodejs. Please itself isreleased by please.

Working Mechanism

Determine remote git repo based on local git config
Checkout and Updatemaster
Get latest release from github api endpoint
Collect new commits since the latest release
Create a changelog (prepend to if exists), reflect that into./CHANGELOG.md file and commit it
Bump the version as per semver, reflect that into./VERSION file and commit it
- If any of the latest commits start withfeat<minor> is bumped
- But if only you didnt explicitly passscope already
If there ispackage.json file, bumppackage.json#version and commit it
Ifpackage.json#private is not set totrue
- If npm user not already logged in, runnpm adduser
- Runnpm publish finally
Release the new version and tag to github
If there isbox.json file, compile phar usingbox(downloadbox.phar if required)
Upload the compiledphar as asset for the recent release

Installation

# Requirements:# jqsudo apt install jq -ycurl -sSLo~/please https://raw.githubusercontent.com/adhocore/please/main/pleasechmod +x~/please&& sudo ln -s~/please /usr/local/bin/please

Setup

One time setup. In your.bashrc /.zshrc or the like export github token:

export GH_AUTH_TOKEN=<your token here>

Get your token fromhere.Make sure to set only bare minimum permission scopes for this token.

What permissions

repoif you want to release private repos
public_reporequired
repo_deploymentrequired

Important: Tokens are to be treated and kept as much secret as passwords.

Usage and Examples

Make sure you have already merged required commits tomaster branch in Github,then go to the root of any project you want to release and run:

please [Scope|Command] [Options]

please v0.11.0 | (c) Jitendra Adhikari | please is semver release made easy.Usage: please [command|scope] [--options]Commands:  version        Print current version of itself.  help           Show help information and usage examples.Scope:  major          Bumps the <major> part of semver.  minor          Bumps the <minor> part of semver.Options:  -c --chlog     Forces creation of CHANGELOG.md file.  -h --help      Show help information and usage.  -H --chash     Prepends commit hash into log.  -o --organize  Commit types as CSV for changelog or release notes.                 (Default: feat,fix,refactor,perf,docs,infra,chore)  -L | --label   Set custom release label.  -N | --no-sync Do not sync the DEPLOY_BRANCH with remote (faster but unsafe).  -p --public    Set scoped npm package for public access.  --prev-version Fix the previous version (skips API call).  -u --update    Update please to latest version.  -v --vfile     Forces creation of VERSION file.  -V --version   Forces the exact version to be released.  -y --yes       Assume yes for any confirmation.Events:  --before-all     Run the command before anything (very start).  --after-version  Run the command after determining next version.  --before-npm     Run the command before releasing to npm.  --before-push    Run the command before pushing code to remote.  --before-vcs     Run the command before releasing to VCS.  --before-phar    Run the command before uploading phar binary.  --after-all      Run the command after everything finishes.Examples:  please  please version                          # prints current version of itself  please --update                         # updates please if new version available  please --organize feat,fix,docs         # includes only features, fixes and docs  please --vfile --chash                  # creates VERSION file, adds commit hash  please minor --public --yes             # releases minor version without asking  please major --vfile --chlog            # releases next major version with VERSION and CHANGELOG files  please --vfile --chlog --version 1.5.0  # releases version 1.5.0 with VERSION and CHANGELOG files  please --before-all 'echo {REPO}'       # before release, runs 'echo {REPO}' with REPO interpolated

To use custom branch from which you want to create release tag, useDEPLOY_BRANCH env var.

Eg:DEPLOY_BRANCH=main please -v -c

Note

If there isVERSION file in project root, you dont need--vfile flag.
If there isCHANGELOG.md file in project root, you dont need--chlog flag.
If there isbox.json file in project root, it builds and releases.phar too.
If no scope is given
- If there is anyfeat: commit, bumps the<minor> part of semver.
- Else bumps the<patch> part of semver.

Events

You can take control of the work flow or execute more tasks by using the event callbacks.When the event commands are triggerred they receive all the variables defined in the then moment.

Currentlyplease supports these events which are executed in following order:

before-all
after-version
before-npm
before-push
before-vcs
after-release
before-phar
after-all

You can either set events as a json file in./please.json or pass them in as option toplease like so:

# run `composer test` before pushing code# send release notification to slack after everything finishesplease --before-push"composer test" --after-all"slack 'Released {REPO}@{NEXT_VERSION}'"

The event passed in as option will have higher precedence than the one read from./please.json

Caveat

Use only single quote in the event command. Eg:please --before-all "echo 'a b c'"

Output

Here's output ofplease in action, releasing0.0.1 of itself:

$ ./please --vfileRepository adhocore/pleaseLog file /tmp/PLZEXKbyFUpdating master ...  DoneGetting latest releases ...  DoneCurrent Version 0.0.0Collecting commits ...  DoneBumping version ...  DoneReleasing 0.0.1 ...  DoneCheck /tmp/PLZEXKbyF for logs

Andhere is colorful screenshot ofplease releasingv0.0.10 ofphint

And here is a preview of allfeatures ofplease in onerelease:

Sample changelog

CHANGELOG.md generated byplease looks like:

##[0.0.1](https://github.com/<repo>/releases/tag/<0.0.1>) (2018-01-01)###Features-**scope**: commit 1 (Author Name)-**scope**: commit 2 (Author Name)...

If you passed in--chash flag then:

##[0.0.1](https://github.com/<repo>/releases/tag/<0.0.1>) (2018-01-01)###Features-**scope**: commit 1 (Author Name)[_hash1_](https://github.com/<repo>/commit/<hash1>)-**scope**: commit 2 (Author Name)[_hash2_](https://github.com/<repo>/commit/<hash2>)...

On subsequent releases new changes are prepended such that latest commits stay at top.

Troubleshooting

If you are usingzsh thenplease might have been already aliased tosudo. To fix this simply run

echo"alias please=/usr/local/bin/please">>~/.zshrcsource~/.zshrc

About

please is semver release made easy, detects current version from API or tags and next version from commits, creates detailed changelogs that are configurable.

github.com/adhocore/please