Skip to content

Latest commit

 

History

History
377 lines (263 loc) · 14.2 KB

CONTRIBUTING.md

File metadata and controls

377 lines (263 loc) · 14.2 KB

Contributing Guidelines

We want to encourage the developer community to contribute to Sa11y. This guide has instructions to install, build, test and contribute to the framework. Adapted from salesforce/lwc.

Before you start, it helps to be familiar with Web Accessibility

Quick start

  1. yarn install to install dependencies
  2. Make changes while building, testing and linting the changed files
  • yarn build:watch
  • yarn test:watch
  • yarn lint:watch
  1. Update changelog with yarn release:changelog
  2. Stage changes in git and do yarn commit to check staged changes and commit them with a formatted commit message
  3. Push changes to feature branch

Requirements

Installation

Set up SSH access to Github if you haven't done so already.

1) Download the repository

git clone [email protected]:salesforce/sa11y.git

2) Install Dependencies

We use yarn because it is significantly faster than npm for our use case. See this command cheat-sheet.

yarn install
  • Have to do this every time there are changes to package.json from external sources e.g. after switching branches or after merging/rebasing
  • If this fails with an error about UNABLE_TO_GET_ISSUER_CERT_LOCALLY, Error: unable to get local issuer certificate, or a registry communication issue then re-verify that step 2 was successful.

Building

When developing typescript compiler can be invoked using the build target. With :watch the compiler would watch for changes and incrementally compile changed sources as required.

yarn build[:watch]

Testing

Unit Testing

When developing, utilize jest unit testing to provide test coverage for new functionality. To run the jest tests use the following command from the root directory:

yarn test

Additionally, the testing can be started in watch mode which allows for automatic test re-runs on a save:

yarn test:watch

To execute a particular test, use the following command:

yarn test <path_to_test>

If you want to debug these tests, you can do as follows:

  1. First, insert a new line in your test where you think it might be failing and type debugger. This will serve as a break point for the debugger to stop at.
  2. Open up Chrome and type in the address bar: chrome://inspect
  3. Click on "Open dedicated DevTools for Node"
  4. In your terminal, type the following command: yarn test:debug <path_to_test>

Your test should now be running in the Chrome debugger. You get your handy console to poke around all sorts of stuff! Now simply hit "Enter" in the terminal running your Jest process anytime you want to re-run your currently selected specs. You'll be dropped right back into the Chrome debugger.

Release

  • Generate Changelog
    • yarn release:changelog
    • Cleanup CHANGELOG to remove references to squashed commits and replace them with references to corresponding PRs where possible
  • yarn release:version to bump versions interactively
    • yarn release:version:auto to automatically determine version bump based on commits
  • To publish packages to npm
    • npm login
    • yarn release:publish
  • Create a release in github
    • Bump version in root package.json to reflect the changes to the packages since last release
      • Use that root version for the github release
    • Add release notes to reflect Changelog since last release
  • If you couldn't make these changes in the last PR that went into master, you can make a separate PR for release
    • Create a release branch from master
    • Commit changes to versions, changelog
      • Changes should be limited to non-source code changes (docs, config)
    • Push the release branch and create a pull request against master
      • with PR title of the format chore(release): ...

Use local npm registry for testing

  • Use verdaccio to spin-up a local npm registry
  • Packages can be published to it by overriding the registry option
    • e.g. yarn release:publish --registry http://localhost:4873/

Editor Configurations

Configuring your editor to use our lint and code style rules will make the code review process delightful!

Types

This project relies on type annotations.

ESLint

Configure your editor to use our eslint configurations.

Git Workflow

The process of submitting a pull request is fairly straightforward and generally follows the same pattern each time:

  1. Fork the repo
  2. Create a feature branch
  3. Make your changes
  4. Rebase
  5. Check your submission
  6. Create a pull request
  7. Update the pull request
  8. Commit Message Guidelines

Fork the repo

Fork the salesforce/sa11y repo. Clone your fork in your local workspace and configure your remote repository settings.

git clone [email protected]:<YOUR-USERNAME>/sa11y.git
cd sa11y
git remote add upstream [email protected]:salesforce/sa11y.git

Create a feature branch

git checkout master
git pull origin master
git checkout -b <name-of-the-feature>

Make your changes

Modify the files, build, test, lint and eventually commit your code using the following command:

git add <path/to/file/to/commit>
yarn commit or git commit
git push origin <name-of-the-feature>

Commit your changes using a descriptive commit message that follows our Commit Message Guidelines. Adherence to these conventions is necessary because release notes are automatically generated from these messages. NOTE: optional use of yarn commit command triggers interactive semantic commit, which prompts user with commit related questions, such as commit type, scope, description, and breaking changes. Use of yarn commit is optional but recommended to ensure format consistency.

The above commands will commit the files into your feature branch. You can keep pushing new changes into the same branch until you are ready to create a pull request.

Rebase

Sometimes your feature branch will get stale with respect to the master branch, and it will require a rebase. The following steps can help:

git checkout master
git pull upstream master
git checkout <name-of-the-feature>
git rebase upstream/master

note: If no conflicts arise, these commands will ensure that your changes are applied on top of the master branch. Any conflicts will have to be manually resolved.

Check your submission

Lint your changes

yarn run lint

The above command may display lint issues that are unrelated to your changes. The recommended way to avoid lint issues is to configure your editor to warn you in real time as you edit the file.

Fixing all existing lint issues is a tedious task so please pitch in by fixing the ones related to the files you make changes to!

Run tests

Test your change by running the unit tests and integration tests. Instructions here.

Test CI config

Optionally test any changes to CI config locally by using the CircleCI local CLI

  • circleci config validate
  • circleci local execute --job build_and_test

Create a pull request

If you've never created a pull request before, follow these instructions. Pull request samples can be found here.

Pull Request Title

A pull request title follows conventional commit format and is automatically validated by our CI.

ex:
commit-type(optional scope): commit description. ( NOTE: space between column and the message )

Types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test, proposal.
Scope: The scope should be the name of the npm package affected (preset-rules, assert, jest, format etc.)

Update the pull request

git fetch origin
git rebase origin/${base_branch}

# If there were no merge conflicts in the rebase
git push origin ${feature_branch}

# If there was a merge conflict that was resolved
git push origin ${feature_branch} --force

note: If more changes are needed as part of the pull request, just keep committing and pushing your feature branch as described above, and the pull request will automatically update.

Commit

Commit Message Conventions

Git commit messages have to be formatted according to a well-defined set of rules. This leads to more readable messages that are easy to follow when looking through the project history.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope, and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory, and the scope of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Footer should contain a closing reference to an issue if any.

Samples: (even more samples)

docs(changelog): update change log to beta.5

fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

Reverting a commit

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Commit Type

Must be one of the following:

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • chore: Other changes that don't modify src or test files
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • revert: Reverts a previous commit
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

Commit Scope

The scope should be the name of the npm package affected, as perceived by the person reading the changelog.

There are currently a few exceptions to the "use package name" rule:

  • root: used for changes that change the npm package layout in all of our packages, e.g. public path changes, package.json changes done to all packages, d.ts file/format changes, changes to bundles, etc.

Commit Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize first letter
  • no dot (.) at the end

Commit Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Commit Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit closes.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.