Skip to content

Latest commit

 

History

History
138 lines (94 loc) · 8.95 KB

CONTRIBUTING.md

File metadata and controls

138 lines (94 loc) · 8.95 KB
Raw

Contributing

Introduction

Thank you for considering contributing! It's people like you that make the open source community so great! 😊

The tips and guidelines below are intended to help both contributors and maintainers respect each other's time and effect change as quickly as possible.

  • Bugs and Feature Requests: Follow the templates here to report problems or ideas. You may be asked for clarification or opinions on solutions.
  • Fixes: Take a look at the open issues. Even if you are unable to implement a solution, commenting on issues with your opinions and experiences is greatly appreciated and helpful for triage.
  • Documentation: Update or add a page to the wiki or improve preexisting documentation to help other users.
  • Something Else?: This list isn't comprehensive so if you have another idea for contribution, please reach out.

Ground Rules

Responsibilities

  • Be welcoming and treat everyone with respect as per the Code of Conduct.
  • Before doing any major work, open an issue to garner community feedback.

Code Contributions

Your First Code Contribution

Working on your first pull request? You can learn how from this free series, How to Contribute to an Open Source Project on GitHub.

Here are some good first issues.

If you get stuck, push your code early and ask for feedback on the issue.

Getting started

  1. After you check out the code, run npm install (npm installation guide) to get the rikaikun dev tools ready.
    1. By default, npm install will also run a test suite and install visual test baselines in the local-screenshots directory.
  2. Make your changes and commit them locally. Run npm run fix often to ensure your code follows style guidelines. This runs before you push by default as well.
  3. Add tests for your new code in the extension/test directory.
    1. If you add a new feature to the in page popup, be sure to add a set of visual screenshot tests for it as well. See e2e_visual_test.js for examples.
  4. Run npm run build to create an unpackaged instance of rikaikun in the dist directory. Load this into Chrome to test your changes.
  5. When you're satisfied with your changes, commit your code, check that your commit message follows these guidelines, and start a pull request.

Testing

rikaikun originally didn't have any tests but we're slowly building up test coverage as new functionality gets added. Right now, testing is focused around unit testing (including screenshot tests) but hopefully e2e testing will be added soon. Testing stack:

  • @web/test-runner is a modern test runner which works with snowpack. It is configured as follows:
    • Framework: The default is Mocha and rikaikun keeps it for its behavior driven testing style.
    • Assertion Library: Chai works well with Mocha; rikaikun uses expect style assertions.
    • Test Doubles: For spies and stubs, rikaikun uses Sinon.JS combined with the sinon-chrome package which provides a complete fake Chrome extensions API.
    • Browser: Test run using headless chrome via Puppeteer.

Philosophy and Best Practices

Testing is an art not a science but what follows is a set of guidelines to help you write tests that are easy to read and maintain.

Reasons for testing
  • Ensures that your code is working as intended.
  • Ensures a minimum amount of composability in your tested code.
  • Acts as living documentation of your code.
Guidelines

For now, follow the advice at this guide. Not every best practice there will apply but it's a great starting point. We can add exceptions and additions here as they come up.

Coverage

After your PR passes presubmit, codecov will add a comment analyzing how your change affects code coverage in the repo. You should have test coverage for all new functionality added in your PR (we don't want it to break!). Sometimes it's hard to understand which branches are missing coverage so please ask if you're having trouble.

Pull Requests

Pull requests (PR) are where the main discussion around how you implemented your change will happen. The following guidelines will ensure a quick and painless merge.

  • Each PR should solve one concern and be of reasonable size. For tips on keeping pull requests small, see the following blog post.
    • Generally, every code change in your PR should be required for your feature or bug fix. If you notice an improvement along the way, please open a new issue for it and submit a new PR. One off improvements are usually OK but mention them explicitly in your commit/PR message.
  • The PR title should be a single descriptive phrase of the one thing the PR accomplishes. This should be the first line of your PR commit.
  • The PR body should give extra details and include links to related issues, pull requests and outside references. This should be the body and footer of your commit.
  • Your PR should start with one commit which contains your new code. During the course of review, it's better to add commits to your branch instead of amending or rebasing because otherwise Github loses the evolution of the code. When your PR is merged, it will be squashed back into one commit.
  • If your PR introduces visual changes, it's normal for the tests to fail in the first pass. After they fail, Github will add a commit to the PR which updates the baselines for easy comparing.
    • This may not work for PRs from forks. In that case, reach out to a maintainer for help. Essentially, you can download the new baseline images as a Github Action artifact and commit them yourself.

Style Guides

Git Commit Messages

rikaikun follows the Conventional Commits specification. This allows us to automatically generate new versions and change logs and reduces some cognitive load when first reading a commit. There is a git commit-msg hook which will ensure commit messages are to spec.

In brief, commit messages should look like:

feat(dict): Update word and name dictionaries to 2020-08-31 snapshots.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

If your change requires a newer version of Chrome than was required previously, include BREAKING CHANGE with an explanation in the footer.

Here are examples of the types currently in use (partial source):

feat (new feature for the user, not a new feature for build script)
fix (bug fix for the user, not a fix to a build script)
docs (changes to the documentation)
style (formatting, missing semi colons, etc; no production code change)
refactor (refactoring production code, eg. renaming a variable)
test (adding missing tests, refactoring tests; no production code change)
build (updating build scripts and NPM dependencies; no production code change)
ci (changing the github checks which continuously run on pushed code)

These are the common scopes used, though feel free to suggest a new one if it makes sense:

Scope Explanation
deps Used when changing the node dependencies of the project.
ui Used for fixes and features affecting the popup UI.
dict Used for fixes and features affecting the dictionary data.

See the (recent) commit history for more examples of correctly formatted messages.

Coding style

As long as npm run lint passes, your code is correctly styled. You may get some more specific advice if a maintainer thinks something is more readable, but it saves a lot of time when we don't have to worry about auto-fixable style issues!