This repository contains common automation tools to be shared among multiple projects, including tools for installing linting rules etc.
All changes to this project should be published under a new version number.
To use this project, first install using
npm i --save-dev alcumus-common-tools, then use the provided binaries to install what you need. For example:
npx common # install the most common options needed (eslint, .editorconfig, git hooks, etc.).npx linting # install eslint.npx linting react # install linters needed for react projectsnpx editor-config # install just .editorconfig file.npx git-hooks # NOT YET IMPLEMENTED: this will install the common git hooks to the project.
npx common forwards any parameters it receives to all of the other commands it triggers so
npx common eslint will call
npx linting eslint.
These commands should create very minimal files within your current project (a symlink where appropriate, a simple config file that just extends the ones from this project elsewhere). In the case of extending config files for linters it also allows us to make project specific changes if appropriate; though this should be a last resort.
Overall we should make our changes in just this project and use npm to upgrade to newer versions in other projects.
In order to test locally, just clone the repo and link a test project to this as follows:
npm link # execute in the root of this project to make npm associate this folder with the correct package.cd <project> # change to your test project.npm link alcumus-common-tools # equivalent of npm i alcumus-common-tools, but creates symlinks in node_modules instead of installing.
To publish changes you've made (and tested locally), just run
npm run publish-new. This will publish to the correct NPM registrar as
well as bumping the version number ready for the next change. For major version changes, first change
package.json to have the correct
version number, then run
npm run publish-new.
To publish a pre-release version of changes you've made (and tested locally), just run
npm run publish-pre-release. This will publish a pre-release version to the correct npm repo using the
version defined in the package json and current branch number in the following format: version-branch-publishVersion (e.g. 0.1.10-HF-563-1) it will then increment
the publish version for each subsequent run of the pre-release job.
Using on Windows
Usage on Windows should be the same as usage on Mac, except that it must be run as an administrator (run your IDE or CMD itself as admin).
A set of git hooks will be installed in the current project when using
npx common. They can also be specifically installed
npx install-git-hooks command. At present these git hooks provide the following functionality:
- Warn when you check out a branch that does not follow the branch naming convention (-) or is specifically exempt (master).
- Ensure that all commit messages are prefixed with the ticket number from the branch they were created on. I.e., if you commit with a message "Fixing unit tests" on branch "HF-99-fixing-framework-bug" your commit message will be automatically changed to "HF-99: Fixing unit tests".
To create more git hooks, simply create a new file with a file name matching any git hook file
name (with .js after it) in
src/git-hooks and run the install again. The files will be symlinked to
making sure they will be updated if the npm module is updated.
This repository exposes a
npx pr command that can be used to create pull requests in a standardised way that can be
extended later. At present, this will ensure that the project passes linting before allowing a PR to be created. In the
future this will be extended to include unit tests passing if present etc. In addition to this, a report can be
generated that will be attached to the PR itself. At the moment this just compares linting pre-PR and post-PR, but can
be extended to show changes in code coverage, etc. In addition to this the command allows an easy way of inviting
people by name or by team. In order to create Bitbucket PRs, appropriate credentials must be available in
~/al-tools.credentials.json structure is as follows:
In order to execute npx commands that are declared in this project from within this project, add
-p .to the command as in
npx -p . pr ...
The JIRA username/password is required to get JIRA descriptions added to your PR, but is otherwise optional. JIRA unfortunately requires you to put your normal username and password in the config file, while Bitbucket allows you to create an app password (see [https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html]).
npx pr -r thor # invite Thor to be a reviewer (this will be matched against both full name and username, case insensitive).npx pr -r pippin mark # invite all of team Pippin and Mark Gabb to be a reviewer.
Any number of reviewers can be added and additional groupings can easily be added by changing the
teams.json file in the S3 bucket
npx pr is a short form of
npx pr create. Additional commands (such as
npx pr update may be created
in the future).
npx pr --help should provide a good idea of the options available, though sensible defaults for merging to
- Add code coverage report to PR.
- Add tasks based on reviewer checklist to PR.
- Stop PR from being created if unit tests fail.
npx pr update- refresh generated content for PR based on changes, but leave other details as they were.
Making a new command available
- Add a
<command>-cli.jsfile that will handle CLI arguments. Bear in mind that your file may be called with arguments that belong to other CLI files so be careful about how you read them.
- Separate the CLI logic from the business logic, business logic goes in
- Add the name of your CLI file to
- If appropriate, add it to
common-cli.js, which is executed for
npx commonas mentioned above.
- Remember to publish the new version when you're done. (When the NPM repo is ready).