Skip to content

Latest commit

 

History

History
232 lines (157 loc) · 12.7 KB

CONTRIBUTING.md

File metadata and controls

232 lines (157 loc) · 12.7 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.

Getting Started

The documentation in this repo is generated using Hexo.

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

Install dependencies:

Note: at least Node 6 is required, but Node 8 with NPM v5 is preferred to take advantage of the package lock file.

npm install

This will install this repo's direct dependencies.

Then, build the public directory and start the app:

npm run build
npm start

Visit http://localhost:2222/.

Note: If you need to debug the documentation build step, run it this way:

DEBUG=docs npm run build

Testing

We use Cypress itself to test the documentation. To start the server and run E2E tests, execute the command npm run test-e2e.

Writing Documentation

Tags

In addition to built-in Hexo tags, we have written several custom ones. They help us write consistent documentation, check referenced urls, etc. You can find the list of tags and examples in TAGS.md.

Adding Examples

To add a course, blog, talk, podcast, or screencast to our docs, submit a pull request with your data added to the corresponding courses.yml, blogs.yml, talks.yml, podcasts.yml or screencasts.yml file.

Add an associated image with the example within the source/img/examples directory. Each image should have a resolution of 715×480. Reference the image in the markdown document as follows:

{% imgTag /img/examples/name-of-file.jpg "alt text describing img" %}

Using images

If you are starting a new page and want to add images, add a new folder to "themes/cypress/source/img". For example when adding a new "Code Coverage" page to "guides/tooling", I have created new folder "themes/cypress/source/img/guides/code-coverage" and copied an image there called "coverage-object.png". From the page itself, I can include the image using imgTag.

{% imgTag /img/guides/code-coverage/coverage-object.png "Code coverage object" %}

Adding Plugins

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

Adding Pages

To add a page such as a new guide or API documentation:

  • Add the new page to the relevant directory under source.
  • Link to your new page in the sidebar.yml.
  • Add translations for the sidebar link for each supported language (for English, this is located in en.yml).
  • Build the documentation site locally so that you can visually inspect your new page and the links to it.
  • REQUIRED: Commit the new file using git - we auto-generate the doc to display within each supported language, this auto-generation depends on the file existing in git.
  • Submit a pull request for your change.

Deleting Pages

To delete a page:

  • Delete the page from the relevant directory under source.
  • Remove the link from the the sidebar.yml.
  • Remove the translations for the sidebar link for each supported language (for English, this is located in en.yml).
  • REQUIRED: Commit the change using git - we auto-remove the doc within each supported language, this auto-generation depends on the file being deleted in git, the build will not work until this is commited.
  • Build the documentation site locally so that you can visually inspect and make sure it was properly deleted.

A Worked Example

Let's imagine that the Cypress team has just added a new command called privateState and you've picked up the task to document it.

API documentation for commands is in the source/api/commands directory.

  1. Add a file called privatestate.md to that directory.
  2. Write the document. Look to the existing documentation to see how to structure the content.
  3. Open the source/_data/sidebar.yml file and add a link the new privatestate page. In this example we're adding a command so we'll add a link underneath the api.commands section.
api:
  commands:
    and: and.html
    as: as.html
    blur: blur.html
    # ...
    privatestate: privatestate.html
  1. Open themes/cypress/languages/en.yml and add an English translation for that sidebar link's title. In this example we're adding a command so we'll add the following text:
sidebar:
  api:
    introduction: Introduction
    api: API
    commands: Commands
    # ...
    privatestate: privateState
  1. Now, copy the new page to the other translated docs. Add a privatestate.md within source/ja/api/commands and source/zh-cn/api/commands with the same content as the original document. Repeat steps 3-4 within the translated directories.
  2. Submit a pull request for your change.

Writing the Changelog

When adding to the Changelog, create a new file in source/_changelogs named as the version number. 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). Be aware that in development, only the five most recent entries will appear but the full changelog will be built in staging and production.

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

Translating

Adding a new language

  1. Add a new language folder in source folder. (All lower case). The folder name should correspond to the language's abbreviation code.
  2. Add the new language to source/_data/languages.yml.
  3. Add the new language to _config.yml under language.
  4. Add the new language index page to _config.yml under alias.
  5. Copy Markdown and template files in source folder to the new language folder.
  6. Copy en.yml in themes/cypress/languages and rename to the abbreviated language name (all lower case).

Translating existing docs

Our currently supported languages can be found at /source/_data/languages.yml. From here, find the corresponding directory within the /source directory that matches the language you want to translate.

Translate existing documentation then submit a pull request for your change.

Note: When adding a new doc file to the English source, the English file will need to be commited to git before the translated file is auto-generated.

If a page does not have a translation, then a pre-start step copies the English file to the language folder. These copies should NOT be committed into the source code. Only when the file has been translated you can add it to the source code with git add --force source/<language>/.../file.md and this file will not be overwritten by the English file.

Committing Code

Linting

Danger 📛: because we are minifying client-side code using a Hexo plugin which in turn calls uglify, the code should be strictly ES5. Thus everything inside the theme should be linted with ES5 settings and not upgraded to ES6.

In addition to ESLint, we use Textlint to lint Markdown files. This currently lints code snippets using the rules in .eslintrc-textlint and checks terminology using the terms in .textlintrc. To disable Textlint for a block, do the following:

<!-- textlint-disable -->
{% video youtube 5XQOK0v_YRE %}
<!-- textlint-enable -->

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 develop branch in cypress-io/cypress-documentation
  • 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

Every pull request merged into develop automatically opens another pull request to master, which should be merged automatically using Mergify Bot after the CircleCI tests pass, see issue #2363.

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, we will deploy it to the staging environment, run E2E tests (using Cypress itself of course!), and then merge it into master, which will deploy it to the official https://docs.cypress.io website. If you want to know our deploy process, read DEPLOY.md.

Trigger workflow build

Due to CircleCI API limitations (even after 2 years), you cannot trigger a workflow build using the API. Thus if you need to build, test and deploy develop branch for example, your best bet is to create an empty GitHub commit in the cypress-io/cypress-documentation repository in the develop 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 master

As always, using as-a is recommended for storing and using sensitive environment variables.