Skip to content

Latest commit

 

History

History
261 lines (197 loc) · 9.92 KB

CONTRIBUTING.md

File metadata and controls

261 lines (197 loc) · 9.92 KB
Raw

Contributing to Cypress Documentation

Thanks for taking the time to contribute! 😄

Table of Contents

Code of Conduct

All contributors are expected to abide by our Code of Conduct.

Writing Documentation

The documentation uses Docusaurus to generate a static website. Refer to the Docusaurus documentation for specifics about the framework.

Fork this repository

Using GitHub, create a copy (a fork) of this repository under your personal account.

Clone your forked repository

git clone [email protected]:<your username>/cypress-documentation.git
cd cypress-documentation

VSCode MDX Extension

If you are using VS Code, download the MDX extension to get full editor support for MDX files.

Admonitions

Use Admonitions to grab the reader's attention with a blurb.

Images

If you are starting a new page and want to add images, add a new folder to static/img. For example when adding a new "Code Coverage" page to guides/tooling, I have created new folder assets/img/guides/tooling and copied an image there called coverage-object.png. Within the markdown, I can include the image using the <DocsImage /> component.

<DocsImage
  src="/img/guides/tooling/coverage-object.png"
  alt="code coverage object"
/>

Typically you should include the alt and title attributes to give the user more information about the image.

Videos

You can embed videos within the markdown with the <DocsVideo /> component. Currently, it supports local files, YouTube, and Vimeo embeds. Set the src prop to a relative path for a local video file or the embed link for YouTube or Vimeo videos. You should also set a title prop describing the video for accessibility reasons.

<DocsVideo
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="Cypress Tips and Tricks"
/>

Icons

Font Awesome icons can be used within markdown by using the <Icon /> component. Set the name prop to the name of the Font Awesome icon you want to use. Make sure that the icon appears in the list of imported icons within the MDXComponents.js file under the fontawesome key.

<Icon name="question-circle" />

Partials

Partials are snippets of reusable markdown that can be inserted into other markdown files. You may want to use a partial when you are writing the same content across multiple markdown files.

You can learn about how to import markdown & partials here.

Adding Plugins

To add a plugin, submit a pull request with the corresponding data added to the plugins.json file. Your plugin should have a name, description, link to the plugin's code, as well as any keywords.

We want to showcase plugins that work and have a good developer experience. This means that a good plugin generally has:

  1. Purpose of plugin articulated up front
  2. Installation guide
  3. Options and API are documented
  4. Easy to follow documentation. Users should not have to read the source code to get things working.

Each plugin submitted to the plugins list should have the following:

  1. Integration tests with Cypress

    • Demonstrates the plugin working
    • Acts as real-world example usage

  2. CI pipeline

  3. Compatibility with at least the latest major version of Cypress

Plugins are listed in in the following order to for users:

  • official
  • verified
  • community
  • experimental

Adding Pages

To add a page, such as a new guide or API documentation check out how to do so here.

Patches

From time to time, we find we need to patch a library using patch-package for various reasons. Each of the patches should be explained below for future understanding.

@docusaurus/mdx-loader patch

Docusaurus lower cases header anchor ids, and to maintain consistency with past docs implementations, we need to preserve the casing of our header ids. This patch passes in the maintainCase option as true to the github slugger to achieve this.

We also opened an issue to add this as a feature to Docusaurus, so if this gets implemented this patch can go away.

Writing the Changelog

When adding to the Changelog, create a new section with the title as the version number on top of the previous section. Be sure to follow the category structure defined below (in this order). Each bullet point in the list should always be associated to an issue on the cypress repo and link to that issue (except for Documentation changes).

Categories

  • Summary - If it is a large release, you may write a summary explaining what the point of this release is (mostly used for breaking releases)
  • Breaking Changes - The users current implementation of Cypress may break after updating.
  • Deprecations - Features have been deprecated, but will not break after updating.
  • Features - A new feature
  • Bugfixes - A bug existed in Cypress and a PR fixed the issue
  • Misc - Not a feature or bugfix, but work that was done. May be internal work that was done and associated with an issue
  • Documentation Changes - our docs were updated based on behavior changes in release

Committing Code

Pull Requests

You should push your local changes to your forked GitHub repository and then open a pull request (PR) from your repo to the cypress-io/cypress-documentation repo.

  • The PR should be from your repository to the appropriate branch in the cypress-io/cypress-documentation repository.
    • For documentation changes that are not tied to a feature release, open a PRs against the main branch.
    • For documentation additions for unreleased features, open a PR against the corresponding X.Y.Z-release branch. Once the release is performed, this branch will be merged into main by the releaser.
  • When opening a PR for a specific issue already open, please use the closes #issueNumber syntax in the pull request description—for example, closes #138—so that the issue will be automatically closed when the PR is merged.
  • Please check the "Allow edits from maintainers" checkbox when submitting your PR. This will make it easier for the maintainers to make minor adjustments, to help with tests or any other changes we may need. Allow edits from maintainers checkbox
  • All PRs against main will automatically create a deploy preview URL with Netlify. The deploy preview can be accessed via the PR's netlify-cypress-docs/deploy-preview status check:

Netlify deploy preview status check

  • All branches will automatically create a branch deploy preview. The branch deploy previews do not appear as a GitHub status check like deploy previews. You can view your branch's deploy preview by visiting https://$BRANCH_NAME--cypress-docs.netlify.app where $BRANCH_NAME is your git branch name. For example, if my branch was named my-branch, my branch preview will be available at https://my-branch--cypress-docs.netlify.app.

Contributor License Agreement

We use a cla-assistant.io web hook to make sure every contributor assigns the rights of their contribution to Cypress.io. If you want to read the CLA agreement, its text is in this gist.

After making a pull request, the CLA assistant will add a review comment. Click on the link and accept the CLA. That's it!

Deployment

We will try to review and merge pull requests as fast as possible. After merging, the changes will be made available on the official https://docs.cypress.io website.

Trigger workflow build

Due to CircleCI API limitations, you cannot trigger a workflow build using the API. Thus if you need to build, test and deploy your-branch branch for example, your best bet is to create an empty GitHub commit in the cypress-io/cypress-documentation repository in the your-branch branch. We have added make-empty-github-commit as a dev dependency and set it as make-empty-commit NPM script in the package.json.

To trigger production rebuild and redeploy, use personal GitHub token and run:

GITHUB_TOKEN=<your token> npm run make-empty-commit -- --message "trigger deploy" --branch main