Skip to content

Latest commit

 

History

History
208 lines (139 loc) · 9.15 KB

CONTRIBUTING.md

File metadata and controls

208 lines (139 loc) · 9.15 KB
Raw

Contributing

Thanks for your interest in contributing to GuardianTest! 😄

Once you learn how to use GuardianTest, you can contribute in lots of ways:

  • Join the GuardianUI Discord and answer questions. Teaching others how to use GuardianTest is a great way to learn more about how it works.
  • Create content about GuardianTest. Whether it's a blog post, youtube video tutorial, tweet, or anything in between, sharing information and guidance is a great way to engage the community. Be sure to tag us on twitter when you post it so we can share it as well. We may also feature it on our website!
  • Contribute to our docs to improve our existing docs.
  • Host a meetup or online workshop. Contact us if you want our help coordinating or potential involvement. 🚀

Interested in contributing to the development of GuardianTest? There are several ways to do so.

If you want to contribute, but aren't sure where to start, you can create a new discussion.


Note

Please review the Discussions or ask first before starting work on any significant new features.

It's never a fun experience to have your pull request declined after investing time and effort into a new feature. To avoid this from happening, we request that contributors create a feature request to first discuss any changes or significant new ideas.


Table of Contents

Code of Conduct

All contributors are expected to follow our Code of Conduct.

Opening Issues

The most important things to do are:

If you've gone through these steps, are up to date, supported, have collected information about the problem, and have the best reproduction instructions you can give, you are ready to open an issue.

Update GuardianTest

Before creating a bug report, make sure you are up to date. Your issue may have already been fixed. Even if you do not see the issue described as resolved in a newer version, a newer version may help in the process of debugging your issue by giving more helpful error messages.

See our documentation on installing GuardianTest

Getting More Information

For some issues, there are places you can check for more information. This may help you resolve the issue yourself. Even if it doesn't, this information can help us figure out and resolve an issue.

  • For issues in the web browser, check the JavaScript console and your Network tab in your DevTools.
  • Click on any command in the Command Log where the failure occurred, this will log more information about the error to the JavaScript console.
  • Ask other GuardianTest users for help in our or Discord.

Complete the Issue Template

Please use the provided issue template to submit your issue. The template includes the information needed for us to continue forward with your problem. Any issues that don't fill out the issue template will be closed.

Describe Your Problem

It can be tempting to provide us with your solution, but the most important thing for you to do is describe your problem first. Understanding your use case will help us contextualize the issue you're facing in relation to similar problems other users may be reporting. Having this context will enable us to find a potentially more impactful solution which may solve several problems at once.

How to Reproduce

It is extremely difficult, if not impossible, for us to resolve issues if we can't reproduce them. The most impactful thing you can do is provide us with a repo with a reproducible bug that can be cloned and run.

Writing Documentation

GuardianTest documentation resides in a separate repo with its own dependencies and build tools. See [Documentation Contributing Guidelines] (INSERT LINK)

Writing Code

Getting Code

Make sure you're running Node.js 14+ and NPM 8+, to verify and upgrade NPM do:

node --version
npm --version
npm i -g npm@latest
  1. Clone this repository
git clone https://github.com/GuardianUI/GuardianTest
cd GuardianTest
  1. Install dependencies
npm install

or

yarn

Code Style

  • Keep the code as clear and self-explanatory as possible.
  • If there is a particularly complicated piece of code or code that was added due to bumping into many implementation issues, add a comment to explain the reasoning.

Commit Messages

Commit messages should follow the Semantic Commit Messages format:

label(namespace): title

description

footer
  1. label is one of the following:
    • fix - GuardianTest bug fixes.
    • feat - GuardianTest features.
    • docs - changes to docs, e.g. docs(api.md): .. to change documentation.
    • test - changes to GuardianTest tests infrastructure.
    • devops - build-related work, e.g. CI related patches and general changes to the browser build infrastructure
    • chore - everything that doesn't fall under previous categories
  2. namespace is put in parenthesis after label and is optional. Must be lowercase.
  3. title is a brief summary of changes.
  4. description is optional, new-line separated from title and is in present tense.
  5. footer is optional, new-line separated from description and contains "fixes" / "references" attribution to github issues.

Example:

chore(mocking): improve consistency of allowance mocking

This patch helps reduce potential issues around value collisions when mocking allowance values.

Fixes #123, fixes #234

Adding New Dependencies

For all dependencies (both installation and development):

  • Do not add a dependency if the desired functionality is easily implementable.
  • If adding a dependency, it should be well-maintained and trustworthy.

A barrier for introducing new installation dependencies is especially high:

  • Do not add installation dependency unless it's critical to project success.

Running and Writing Tests

  • Every feature should be accompanied by a test.

  • Every public api event/method should be accompanied by a test.

  • Tests should be hermetic. Tests should not depend on external services.

  • Tests should work on all three platforms: Mac, Linux and Windows. This is especially important for screenshot tests.

  • Tests are currently written with jest

  • To run all tests:

npm run test:unit

or

yarn test:unit

Contributor License Agreement

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit our CLA.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Attribution

Both Playright and Cypress have fantastic docs and processes. Many areas of our docs are inspired by their docs 🤝