Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add maintainers guide #272

Merged
merged 3 commits into from
Oct 3, 2019
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 93 additions & 0 deletions .github/maintainers_guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Maintainers Guide

This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain
this project. If you use this package within your own software as is but don't plan on modifying it, this guide is
**not** for you.

## Tools

All you need to work with this project is a supported version of [Node.js](https://nodejs.org/en/)
(see `package.json` field "engines") and npm (which is distributed with Node.js).

## Tasks

### Testing

This package has unit tests for most files in the same directory the code is in with the suffix `.spec` (i.e. `exampleFile.spec.ts`). You can run the entire test suite using the npm script `npm test`. This command is also executed by Travis, the continuous integration service, for every Pull Request and branch. The coverage is computed with the `codecode` package. The tests themselves are run using the `mocha` test runner.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Considering the following statement,

Test code should be written in syntax that runs on the oldest supported Node.js version, without transpiling.

the example file name exampleFile.spec.ts needs to be exampleFile.spec.js.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, no. All the tests in this project are written in TS. Therefore, just removing the part , without transpiling would be fine. 👍


Test code should be written in syntax that runs on the oldest supported Node.js version. This ensures that backwards compatibility is tested and the APIs look reasonable in versions of Node.js that do not support the most modern syntax.

A useful trick for debugging inside tests is to use the Chrome Debugging Protocol feature of Node.js to set breakpoints and interactively debug. In order to do this you must run mocha directly. This means that you should have already linted the source (`npm run lint`), manually. You then run the tests using the following command: `./node_modules/.bin/mocha test/{test-name}.js --debug-brk --inspect` (replace {test-name} with an actual test file).

### Generating Documentation

The documentation is built using [Jekyll](https://jekyllrb.com/) and hosted with GitHub Pages.
The source files are contained in the `docs` directory. They are broken up into the `_basic`, `_advanced`, and `_tutorials` directories depending on content's nature.

All documentation contains [front matter](https://jekyllrb.com/docs/front-matter/) that indicates the section's title, slug (for header), respective language, and if it's not a tutorial it contains the order it should appear within it's respective section (basic or advanced).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, the maintainers need to be aware of also updating Japanese translation (plus we may have other languages as well in the future) when they update documents.

I'm still not sure what the most easy-to-understand way to communicate regarding this matter for contributors is but one thing I can suggest is to have a more comprehensive checklist with categories (e.g., code change, documents, etc) in .github/pull_request_template.md.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think pull_request_template.md may be a good place to indicate this. Maybe we could add a label for documentation that is Needs Translation, but I also don't want to wait to merge PRs that aren't translated yet since that could take some time.


To build the docs locally, you can run `bundle exec jekyll serve`.

### Releasing

1. Create the commit for the release:
* Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `package.json`.
* Commit with a message including the new version number. For example `v1.0.8`.
* Tag the commit with the version number. For example `v1.0.8`.

2. Merge into master repository
* Create a pull request with the commit that was just made. Be certain to include the tag. For
example: `git push username master:rel-v1.0.8 && git push --tags username`.
* Once tests pass and a reviewer has approved, merge the pull request. You will also want to
update your local `master` branch.

3. Distribute the release
* Publish to the package manager. Once you have permission to publish on npm, you can run `npm publish`.
* Create a GitHub Release with release notes. Release notes should mention contributors (@-mentions) and issues/PRs (#-mentions) for the release.

4. (Slack Internal) Communicate the release internally. Include a link to the GitHub Release.

5. Announce on community.slack.com in #slack-api

## Workflow

### Versioning and Tags

This project is versioned using [Semantic Versioning](http://semver.org/), particularly in the
[npm flavor](https://docs.npmjs.com/getting-started/semantic-versioning). Each release is tagged
using git.

### Branches

`master` is where active development occurs. Long running named feature branches are occasionally
created for collaboration on a feature that has a large scope (because everyone cannot push commits
to another person's open Pull Request). At some point in the future after a major version increment,
there may be maintenance branches for older major versions.

### Issue Management

Labels are used to run issues through an organized workflow. Here are the basic definitions:

* `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been
documented and the issue has been reproduced.
* `enhancement`: A feature request for something this package might not already do.
* `docs`: An issue that is purely about documentation work.
* `tests`: An issue that is purely about testing work.
* `needs feedback`: An issue that may have claimed to be a bug but was not reproducible, or was otherwise missing some information.
* `discussion`: An issue that is purely meant to hold a discussion. Typically the maintainers are looking for feedback in this issues.
* `question`: An issue that is like a support request because the user's usage was not correct.
* `semver:major|minor|patch`: Metadata about how resolving this issue would affect the version number.
* `security`: An issue that has special consideration for security reasons.
* `good first contribution`: An issue that has a well-defined relatively-small scope, with clear expectations. It helps when the testing approach is also known.
* `duplicate`: An issue that is functionally the same as another issue. Apply this only if you've linked the other issue by number.

**Triage** is the process of taking new issues that aren't yet "seen" and marking them with a basic
level of information with labels. An issue should have **one** of the following labels applied:
`bug`, `enhancement`, `question`, `needs feedback`, `docs`, `tests`, or `discussion`.

Issues are closed when a resolution has been reached. If for any reason a closed issue seems
relevant once again, reopening is great and better than creating a duplicate issue.

## Everything else

When in doubt, find the other maintainers and ask.