ncu-team: add docs

Author: gerkai

README.md

@@ -26,6 +26,8 @@ CLI tools for Node.js Core collaborators.
   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.
 
 ## Usage
 
@@ -53,14 +55,20 @@ Most of the tools need your GitHub credentials to work. You can either
 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.
 
-Note: We need to read the email of the PR author in order to check if it matches
-the email of the commit author. This requires checking the box `user:email` when
-you create the personal access token (you can edit the permission later as well).
+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.
+
+You can also edit the permission of existing tokens later.
 
-Then create an rc file (`~/.ncurc` or `$XDG_CONFIG_HOME/ncurc`):
+After the token is generated, create an rc file with the following content:
+(`~/.ncurc` or `$XDG_CONFIG_HOME/ncurc`):
 
 ```json
 {

docs/ncu-team.md

@@ -0,0 +1,73 @@
+# ncu-team
+
+Listing members of a specific team, synchronize special blocks in files with
+the list of members.
+
+## Usage
+
+### List the members in a team
+
+The members will be sorted alphabetically by their login.
+
+```
+$ ncu-team list automation-collaborators
+
+- [@evanlucas](https://github.com/evanlucas) - Evan Lucas
+- [@joyeecheung](https://github.com/joyeecheung) - Joyee Cheung
+- [@MylesBorins](https://github.com/MylesBorins) - Myles Borins
+- [@nodejs-github-bot](https://github.com/nodejs-github-bot) - Node.js GitHub Bot
+- [@rvagg](https://github.com/rvagg) - Rod Vagg
+- [@targos](https://github.com/targos) - Michaël Zasso
+```
+
+### Synchronize files with special blocks
+
+`ncu-team sync` updates the special block `<!-- ncu-team-sync.team($org/$team) -->`
+with a list of members under the specified team.
+
+For example, if there is a file named `README.md` with text like this:
+
+```markdown
+## Collaborators in the automation team
+
+<!-- ncu-team-sync.team(nodejs/automation-collaborators) -->
+
+<!-- ncu-team-sync end -->
+
+## Bots in the Node.js organization
+
+<!-- ncu-team-sync.team(nodejs/bots) -->
+
+<!-- ncu-team-sync end -->
+```
+
+Running this command:
+
+```
+$ ncu-team sync README.md
+```
+
+will update the file with text like this:
+
+```markdown
+## Collaborators in the automation team
+
+<!-- ncu-team-sync.team(nodejs/automation-collaborators) -->
+
+- [@evanlucas](https://github.com/evanlucas) - Evan Lucas
+- [@joyeecheung](https://github.com/joyeecheung) - Joyee Cheung
+- [@MylesBorins](https://github.com/MylesBorins) - Myles Borins
+- [@nodejs-github-bot](https://github.com/nodejs-github-bot) - Node.js GitHub Bot
+- [@rvagg](https://github.com/rvagg) - Rod Vagg
+- [@targos](https://github.com/targos) - Michaël Zasso
+
+<!-- ncu-team-sync end -->
+
+## Bots in the Node.js organization
+
+<!-- ncu-team-sync.team(nodejs/bots) -->
+
+- [@nodejs-github-bot](https://github.com/nodejs-github-bot) - Node.js GitHub Bot
+
+<!-- ncu-team-sync end -->
+```