Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nodejs/node-core-utils
CLI tools for Node.js Core collaborators
https://github.com/nodejs/node-core-utils
node nodejs
Last synced: 1 day ago
JSON representation
CLI tools for Node.js Core collaborators
- Host: GitHub
- URL: https://github.com/nodejs/node-core-utils
- Owner: nodejs
- License: mit
- Created: 2017-10-22T12:27:44.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-10-04T17:23:49.000Z (3 months ago)
- Last Synced: 2024-10-29T17:38:50.886Z (2 months ago)
- Topics: node, nodejs
- Language: JavaScript
- Homepage: https://nodejs.github.io/node-core-utils/
- Size: 2.19 MB
- Stars: 253
- Watchers: 22
- Forks: 112
- Open Issues: 67
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Node.js Core Utilities
[](https://npmjs.org/package/@node-core/utils)
[](https://github.com/nodejs/node-core-utils/workflows/Node.js%20CI/badge.svg?branch=main)
[](https://codecov.io/gh/nodejs/node-core-utils)
[](https://snyk.io/test/github/nodejs/node-core-utils)
CLI tools for Node.js Core collaborators.
- [Tools](#tools)
- [Usage](#usage)
- [Install](#install)
- [Setting up GitHub credentials](#setting-up-github-credentials)
- [Setting up Jenkins credentials](#setting-up-jenkins-credentials)
- [Make sure your credentials won't be committed](#make-sure-your-credentials-wont-be-committed)
- [Shell autocomplete](#shell-autocomplete)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
## Tools
- [`git-node`](./docs/git-node.md): Custom Git commands for working with Node.js
core, e.g. landing Pull Requests.
- [`ncu-config`](./docs/ncu-config.md): Configure variables for node-core-utils
to use.
- [`ncu-team`](./docs/ncu-team.md): Listing members of a team, synchronizing
special blocks in files with the list of members.
- [`get-metadata`](./docs/get-metadata.md): Retrieving metadata for a Pull Request.
**DEPRECATED**: use [`git node metadata`](./docs/git-node.md#git-node-metadata)
instead.
- [`ncu-ci`](./docs/ncu-ci.md): Parse the results of a Jenkins CI run and display a summary for all the failures.
## Usage
### Install
```
npm install -g @node-core/utils
```
If you would prefer to build from the source, install and link:
```
git clone [email protected]:nodejs/node-core-utils.git
cd node-core-utils
npm install
npm link
```
### Setting up GitHub credentials
Most of the tools need your GitHub credentials to work. You can either
1. Run any of the tools and you will be asked in a prompt to provide your
username and password in order to create a personal access token.
2. Or, create a personal access token yourself on GitHub, then set them up
using an editor.
If you prefer option 2, [follow these instructions](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
to create the token.
When creating the token, the following boxes need to be checked:
- `user:email`: Used by `git-node` and `get-metadata` to read the email of the
PR author in order to check if it matches the email of the commit author.
- `read:org`: Used by `ncu-team` to read the list of team members.
Optionally, if you want to grant write access so `git-node` can write comments:
- `public_repo` (or `repo` if you intend to work with private repositories).
You can also edit the permission of existing tokens later.
After the token is generated, create an rc file with the following content:
(`~/.ncurc` or `$XDG_CONFIG_HOME/ncurc`):
```json
{
"username": "your_github_username",
"token": "token_that_you_created"
}
```
Note: you could use `ncu-config` to configure these variables, but it's not
recommended to leave your tokens in your command line history.
### Setting up Jenkins credentials
The `git-node` and `ncu-ci` commands need to query the Node.js Jenkins API for
CI results, so you'll need to configure the Jenkins API token before using
these commands.
To obtain the Jenkins API token
1. Open
`https://ci.nodejs.org/user//configure` (replace
\ with your own GitHub username).
2. Click on the `ADD NEW TOKEN` button in the `API Token` section.
3. Enter an identifiable name (for example, `node-core-utils`) for this
token in the inbox that appears, and click `GENERATE`.
4. Copy the generated token.
5. Add it into your `ncurc` file (`~/.ncurc` or `$XDG_CONFIG_HOME/ncurc`)
with `jenkins_token` as key, like this:
```json
{
"username": "your_github_username",
"token": "your_github_token",
"jenkins_token": "your_jenkins_token"
}
```
### Make sure your credentials won't be committed
Put the following entries into your
[global `gitignore` file](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreexcludesFile)
(`$XDG_CONFIG_HOME/git/ignore` or a file specified by `core.excludesFile`):
```
# node-core-utils configuration file
.ncurc
# node-core-utils working directory
.ncu
```
Mind that `.ncu/land` could contain your access token since it contains the
serialized configurations.
If you ever accidentally commit your access token on GitHub, you can simply
revoke that token and use a new one.
### Shell autocomplete
To add autocomplete just run `git-node completion` and follow the instructions.
(same for the rest of the tools)
### Troubleshooting
If you encounter an error that you cannot fix by yourself, please
1. Make sure you update NCU to the latest version
2. Try again with the `NCU_VERBOSITY=debug` environment variable set and
open an issue at https://github.com/nodejs/node-core-utils/issues with
detailed logs.
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
MIT. See [LICENSE](./LICENSE).