{"id":13697767,"url":"https://github.com/adhocore/please","last_synced_at":"2025-04-14T23:31:57.654Z","repository":{"id":66360155,"uuid":"143002012","full_name":"adhocore/please","owner":"adhocore","description":"please is semver release made easy, detects current version from API or tags and next version from commits, creates detailed changelogs that are configurable.","archived":false,"fork":false,"pushed_at":"2023-03-25T14:30:58.000Z","size":173,"stargazers_count":86,"open_issues_count":3,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T12:21:13.485Z","etag":null,"topics":["adhocore","changelog","changelog-format","changelog-formatter","changelog-generator","generate-changelog","npm-publish","phar-release","php-release","please","release","release-anything","release-management","semver","semver-release"],"latest_commit_sha":null,"homepage":"https://github.com/adhocore/please","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adhocore.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"adhocore","custom":["https://paypal.me/ji10"]}},"created_at":"2018-07-31T10:55:34.000Z","updated_at":"2023-11-03T16:55:22.000Z","dependencies_parsed_at":"2024-04-08T03:12:02.609Z","dependency_job_id":null,"html_url":"https://github.com/adhocore/please","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhocore%2Fplease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhocore%2Fplease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhocore%2Fplease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adhocore%2Fplease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adhocore","download_url":"https://codeload.github.com/adhocore/please/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248978902,"owners_count":21192871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adhocore","changelog","changelog-format","changelog-formatter","changelog-generator","generate-changelog","npm-publish","phar-release","php-release","please","release","release-anything","release-management","semver","semver-release"],"created_at":"2024-08-02T18:01:02.529Z","updated_at":"2025-04-14T23:31:57.411Z","avatar_url":"https://github.com/adhocore.png","language":"Shell","funding_links":["https://github.com/sponsors/adhocore","https://paypal.me/ji10","https://www.paypal.me/ji10/15usd","https://www.paypal.me/ji10/25usd","https://www.paypal.me/ji10/50usd"],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# adhocore/please\n\n[![Latest Version](https://img.shields.io/github/release/adhocore/please.svg?style=flat-square)](https://github.com/adhocore/please/releases)\n[![Travis Build](https://img.shields.io/travis/com/adhocore/please/master.svg?style=flat-square)](https://travis-ci.com/adhocore/please?branch=master)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)\n[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=This+console+tool+makes+Semver+release+and+changelog+super+easy\u0026url=https://github.com/adhocore/please\u0026hashtags=console,releaser,semver,changelog,gitrelease)\n[![Support](https://img.shields.io/static/v1?label=Support\u0026message=%E2%9D%A4\u0026logo=GitHub)](https://github.com/sponsors/adhocore)\n\u003c!-- [![Donate 15](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square\u0026label=donate+15)](https://www.paypal.me/ji10/15usd)\n[![Donate 25](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square\u0026label=donate+25)](https://www.paypal.me/ji10/25usd)\n[![Donate 50](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square\u0026label=donate+50)](https://www.paypal.me/ji10/50usd) --\u003e\n\n\n`please` (aka **p**hp re**lease** or even n**p**m re**lease**) is very simple Github+NPM release for ~PHP and/or Nodejs projects~ anything.\n\nAssumes you like semantic versioning of the format `\u003cmajor\u003e.\u003cminor\u003e.\u003cpatch\u003e` and you have the commits are following [angular format](https://gist.github.com/brianclements/841ea7bffdb01346392c)!\nMore on this format [here](https://nitayneeman.com/posts/understanding-semantic-commit-messages-using-git-and-angular/).\n\nActually you can release any thing not just PHP/Nodejs. Please itself is [released](https://github.com/adhocore/please/releases) by please.\n\n![Help Preview](https://imgur.com/BOrHs9E.png \"Help Preview\")\n\n#### Working Mechanism\n\n- Determine remote git repo based on local git config\n- Checkout and Update `master`\n- Get latest release from github api endpoint\n- Collect new commits since the latest release\n- Create a changelog (prepend to if exists), reflect that into `./CHANGELOG.md` file and commit it\n- Bump the version as per semver, reflect that into `./VERSION` file and commit it\n    - If any of the latest commits start with `feat` `\u003cminor\u003e` is bumped\n    - But if only you didnt explicitly pass `scope` already\n- If there is `package.json` file, bump `package.json#version` and commit it\n- If `package.json#private` is not set to `true`\n    - If npm user not already logged in, run `npm adduser`\n    - Run `npm publish` finally\n- Release the new version and tag to github\n- If there is `box.json` file, compile phar using `box`\n    (download `box.phar` if required)\n- Upload the compiled `phar` as asset for the recent release\n\n## Installation\n\n```sh\n# Requirements:\n# jq\nsudo apt install jq -y\n\ncurl -sSLo ~/please https://raw.githubusercontent.com/adhocore/please/main/please\nchmod +x ~/please \u0026\u0026 sudo ln -s ~/please /usr/local/bin/please\n```\n\n## Setup \n\nOne time setup. In your `.bashrc` / `.zshrc` or the like export github token:\n\n```sh \nexport GH_AUTH_TOKEN=\u003cyour token here\u003e\n```\n\nGet your token from [here](https://github.com/settings/tokens/new). \nMake sure to set only bare minimum permission scopes for this token.\n\n### What permissions\n\n\u003e - [x] repo               *if you want to release private repos*\n\u003e   - [x] public_repo      *required*\n\u003e   - [x] repo_deployment  *required*\n\n**Important**: Tokens are to be treated and kept as much secret as passwords.\n\n## Usage and Examples\n\nMake sure you have already merged required commits to `master` branch in Github,\nthen go to the root of any project you want to release and run:\n\n```sh\nplease [Scope|Command] [Options]\n```\n\n```\nplease v0.11.0 | (c) Jitendra Adhikari | please is semver release made easy.\n\nUsage: please [command|scope] [--options]\n\nCommands:\n  version        Print current version of itself.\n  help           Show help information and usage examples.\nScope:\n  major          Bumps the \u003cmajor\u003e part of semver.\n  minor          Bumps the \u003cminor\u003e part of semver.\nOptions:\n  -c --chlog     Forces creation of CHANGELOG.md file.\n  -h --help      Show help information and usage.\n  -H --chash     Prepends commit hash into log.\n  -o --organize  Commit types as CSV for changelog or release notes.\n                 (Default: feat,fix,refactor,perf,docs,infra,chore)\n  -L | --label   Set custom release label.\n  -N | --no-sync Do not sync the DEPLOY_BRANCH with remote (faster but unsafe).\n  -p --public    Set scoped npm package for public access.\n  --prev-version Fix the previous version (skips API call).\n  -u --update    Update please to latest version.\n  -v --vfile     Forces creation of VERSION file.\n  -V --version   Forces the exact version to be released.\n  -y --yes       Assume yes for any confirmation.\nEvents:\n  --before-all     Run the command before anything (very start).\n  --after-version  Run the command after determining next version.\n  --before-npm     Run the command before releasing to npm.\n  --before-push    Run the command before pushing code to remote.\n  --before-vcs     Run the command before releasing to VCS.\n  --before-phar    Run the command before uploading phar binary.\n  --after-all      Run the command after everything finishes.\nExamples:\n  please\n  please version                          # prints current version of itself\n  please --update                         # updates please if new version available\n  please --organize feat,fix,docs         # includes only features, fixes and docs\n  please --vfile --chash                  # creates VERSION file, adds commit hash\n  please minor --public --yes             # releases minor version without asking\n  please major --vfile --chlog            # releases next major version with VERSION and CHANGELOG files\n  please --vfile --chlog --version 1.5.0  # releases version 1.5.0 with VERSION and CHANGELOG files\n  please --before-all 'echo {REPO}'       # before release, runs 'echo {REPO}' with REPO interpolated\n```\n\u003e To use custom branch from which you want to create release tag, use `DEPLOY_BRANCH` env var.\n \n\u003e Eg: `DEPLOY_BRANCH=main please -v -c` \n\n#### Note\n\n- If there is `VERSION` file in project root, you dont need `--vfile` flag.\n- If there is `CHANGELOG.md` file in project root, you dont need `--chlog` flag.\n- If there is `box.json` file in project root, it builds and releases `.phar` too.\n- If no scope is given\n  - If there is any `feat:` commit, bumps the `\u003cminor\u003e` part of semver.\n  - Else bumps the `\u003cpatch\u003e` part of semver.\n\n### Events\nYou can take control of the work flow or execute more tasks by using the event callbacks.\nWhen the event commands are triggerred they receive all the variables defined in the then moment.\n\nCurrently `please` supports these events which are executed in following order:\n\n-  before-all\n-  after-version\n-  before-npm\n-  before-push\n-  before-vcs\n-  after-release\n-  before-phar\n-  after-all\n\nYou can either set events as a json file in [./please.json](./please.json) or pass them in as option to `please` like so:\n```sh\n# run `composer test` before pushing code\n# send release notification to slack after everything finishes\nplease --before-push \"composer test\" --after-all \"slack 'Released {REPO}@{NEXT_VERSION}'\"\n```\n\n\u003e The event passed in as option will have higher precedence than the one read from `./please.json`\n\n#### Caveat\nUse only single quote in the event command. Eg: `please --before-all \"echo 'a b c'\"`\n\n### Output\n\nHere's output of [please](./please) in action, releasing [0.0.1](https://github.com/adhocore/please/releases/tag/0.0.1) of itself:\n\n```\n$ ./please --vfile\nRepository adhocore/please\nLog file /tmp/PLZEXKbyF\nUpdating master ...\n  Done\nGetting latest releases ...\n  Done\nCurrent Version 0.0.0\nCollecting commits ...\n  Done\nBumping version ...\n  Done\nReleasing 0.0.1 ...\n  Done\nCheck /tmp/PLZEXKbyF for logs\n```\n\nAnd [here](https://i.imgur.com/mQaiAuk.png) is colorful screenshot of `please` releasing [v0.0.10](https://github.com/adhocore/phint/releases/v0.0.10) of [phint](https://github.com/adhocore/phint)\n\nAnd here is a preview of all [features](https://www.npmjs.com/package/@adhocore/devnull) of `please` in one [release](https://github.com/adhocore/dev-null/releases/tag/0.0.6):\n![Full Preview](https://imgur.com/anzTcrX.png \"Full Feature Preview\")\n\n### Sample changelog\n\n[CHANGELOG.md](./CHANGELOG.md) generated by `please` looks like:\n\n```md\n## [0.0.1](https://github.com/\u003crepo\u003e/releases/tag/\u003c0.0.1\u003e) (2018-01-01)\n\n### Features\n- **scope**: commit 1 (Author Name)\n- **scope**: commit 2 (Author Name)\n...\n```\n\nIf you passed in `--chash` flag then:\n\n```md\n## [0.0.1](https://github.com/\u003crepo\u003e/releases/tag/\u003c0.0.1\u003e) (2018-01-01)\n\n### Features\n- **scope**: commit 1 (Author Name) [_hash1_](https://github.com/\u003crepo\u003e/commit/\u003chash1\u003e)\n- **scope**: commit 2 (Author Name) [_hash2_](https://github.com/\u003crepo\u003e/commit/\u003chash2\u003e)\n...\n```\n\nOn subsequent releases new changes are prepended such that latest commits stay at top.\n\n### Troubleshooting\n\nIf you are using `zsh` then `please` might have been already aliased to `sudo`. To fix this simply run\n\n```sh\necho \"alias please=/usr/local/bin/please\" \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadhocore%2Fplease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadhocore%2Fplease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadhocore%2Fplease/lists"}