Skip to content

Latest commit

 

History

History
389 lines (269 loc) · 14.8 KB

CONTRIBUTING.md

File metadata and controls

389 lines (269 loc) · 14.8 KB
Raw

Contributing Guidelines

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

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

Quick start

  1. yarn clean to remove installed dependencies and clean dist folders
  2. yarn install to install dependencies
  3. 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 git@github.com:salesforce/sa11y.git

2) Install Dependencies

We use yarn]. See this CLI commands comparison cheat-sheet if you are used to npm.

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>

To debug unit tests

  1. Insert debugger in a new line in your code where you think it might be failing. This will serve as a break point for the debugger to stop at.
  2. Optionally run only a specific test by using it.only(..)
  3. Open up Chrome and type in the address bar: chrome://inspect
  4. Click on "Open dedicated DevTools for Node"
  5. 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.

Integration Testing

  • Integration tests are available for certain packages executed using WebdriverIO
  • Run with yarn test:wdio
  • To debug WebdriverIO tests
    • Add await browser.debug(); to introduce a breakpoint
    • Run test using yarn test:debug or DEBUG=true yarn test
      • To apply different configuration settings to aid debugging (e.g. disable headless, increase timeouts, increase logging)

Release

  • Merge to the default branch. This project uses semantic-release, so your changes will be released immediately. The version bump comes from the conventional commit type:
Type Release type Trigger a release
breaking change major Yes
feat minor yes
fix patch yes
perf patch yes
docs(README) patch yes

Making a pre-release

  • Merge to the alpha branch. It will always publish with the NPM @alpha tag.

Upgrade dependencies

  • yarn install:update
    • Select dependencies to update
  • Check for GitHub Action updates

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 git@github.com:<YOUR-USERNAME>/sa11y.git
cd sa11y
git remote add upstream git@github.com: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.

Media files

Media files such as screenshots, images and demo videos are uploaded into a separate media branch. The uploaded files are then linked/referenced from the media branch to the other branches. This helps manage the binary assets separately without bloating the history/size of the main repo.

Update dependency graph

  • Generate dependency graph using yarn pkg:depgraph
    • Check if dependency graph needs to be updated using yarn lint:depgraph

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.

  • yarn 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.