doc updates

Author: emilyrohrbough

CODE_OF_CONDUCT.md

@@ -1,75 +1,2 @@
-# Contributor Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of
-experience, nationality, personal appearance, race, religion, or sexual identity
-and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-- Using welcoming and inclusive language
-- Being respectful of differing viewpoints and experiences
-- Gracefully accepting constructive criticism
-- Focusing on what is best for the community
-- Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-- The use of sexualized language or imagery and unwelcome sexual attention or
-  advances
-- Trolling, insulting/derogatory comments, and personal or political attacks
-- Public or private harassment
-- Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-- Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, or to ban temporarily or permanently any
-contributor for other behaviors that they deem inappropriate, threatening,
-offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at
-[[email protected]](mailto:[email protected]). All complaints will be reviewed and
-investigated and will result in a response that is deemed necessary and
-appropriate to the circumstances. The project team is obligated to maintain
-confidentiality with regard to the reporter of an incident. Further details of
-specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 1.4, available at
-https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
+Please review our
+[Code of Conduct](https://github.com/cypress-io/cypress/blob/develop/CODE_OF_CONDUCT.md).

CONTRIBUTING.md

@@ -5,37 +5,35 @@ Thanks for taking the time to contribute! :smile:
 ## Table of Contents
 
 - [Contributing to Cypress Documentation](#contributing-to-cypress-documentation)
-  - [Table of Contents](#table-of-contents)
   - [Code of Conduct](#code-of-conduct)
   - [Writing Documentation](#writing-documentation)
     - [Using Vue Components](#using-vue-components)
       - [Alerts](#alerts)
-    - [Images](#images)
-    - [Videos](#videos)
-    - [Icons](#icons)
+      - [Images](#images)
+      - [Videos](#videos)
+      - [Icons](#icons)
     - [Partials](#partials)
       - [Writing a Partial](#writing-a-partial)
       - [Using Partials](#using-partials)
-      - [When to use Partials instead of Vue components](#when-to-use-partials-instead-of-vue-components)
       - [Limitations](#limitations)
+    - [When to use Partials instead of Vue components](#when-to-use-partials-instead-of-vue-components)
     - [Adding Examples](#adding-examples)
     - [Adding Plugins](#adding-plugins)
     - [Adding Pages](#adding-pages)
-    - [Deleting Pages](#deleting-pages)
       - [A Worked Example](#a-worked-example)
-    - [Writing the Changelog](#writing-the-changelog)
-      - [Categories](#categories)
+    - [Deleting Pages](#deleting-pages)
   - [Committing Code](#committing-code)
-    - [Linting](#linting)
     - [Pull Requests](#pull-requests)
+    - [Writing the Changelog](#writing-the-changelog)
+      - [Categories](#categories)
     - [Contributor License Agreement](#contributor-license-agreement)
   - [Deployment](#deployment)
     - [Trigger workflow build](#trigger-workflow-build)
 
 ## Code of Conduct
 
 All contributors are expected to abide by our
-[Code of Conduct](https://github.com/cypress-io/cypress/wiki/code-of-conduct).
+[Code of Conduct](https://github.com/cypress-io/cypress/blob/develop/CODE_OF_CONDUCT.md).
 
 ## Writing Documentation
 
@@ -75,7 +73,7 @@ prop to `info`, `tip`, `warning`, or `danger`.
 <Alert type="info">This is an important message.</Alert>
 ```
 
-### Images
+#### Images
 
 If you are starting a new page and want to add images, add a new folder to
 [`assets/img`](/assets/img). For example when adding a new "Code Coverage" page
@@ -94,7 +92,7 @@ include the image using the
 Typically you should include the `alt` and `title` attributes to give the user
 more information about the image.
 
-### Videos
+#### Videos
 
 You can embed videos within the markdown with the
 [`<DocsVideo>`](/components/global/DocsVideo.vue) component. Currently, it
@@ -110,10 +108,11 @@ accessibility reasons.
 >
 ```
 
-### Icons
+#### Icons
 
-[Font Awesome](https://fontawesome.com/) icons can be used within markdown. Set
-the `name` prop to the name of the Font Awesome icon. Make sure that the icon
+[Font Awesome](https://fontawesome.com/) icons can be used within markdown by
+using the [`<Icon>`](/components/global/Icon.vue) 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 `nuxt.config.js` file under the
 `fontawesome` key.
 
@@ -165,7 +164,17 @@ within the `content` directory. You must provide the path relative to the
 `pizza-recipe.md` was located at `/content/recipes/pizza-recipe.md`, the
 `::include` directive would be `::include{file=recipes/pizza-recipe.md}`.
 
-#### When to use Partials instead of Vue components
+#### Limitations
+
+When including the `::include{file=FILE_NAME}` directive in another markdown
+file, Nuxt's hot module reloading will automatically trigger the partial's
+content to be inserted into the markdown file. However, if you wish to make
+changes to the partial file itself, you will need to stop and restart the
+development server with `yarn start` to see the changes. This is because the
+custom remark plugin that is enabling this partial system is only ran when the
+server is started and not on each hot module reload.
+
+### When to use Partials instead of Vue components
 
 It is possible to create partials using Vue components in the markdown instead
 of using the `::include{file=FILE_NAME}` directive. However, there are downsides
@@ -184,16 +193,6 @@ when you want to inject reusable markdown into multiple files. A `<Partial>` Vue
 component may be a better fit if you wish to add custom interactivity to
 reusable strings of text.
 
-#### Limitations
-
-When including the `::include{file=FILE_NAME}` directive in another markdown
-file, Nuxt's hot module reloading will automatically trigger the partial's
-content to be inserted into the markdown file. However, if you wish to make
-changes to the partial file itself, you will need to stop and restart the
-development server with `yarn start` to see the changes. This is because the
-custom remark plugin that is enabling this partial system is only ran when the
-server is started and not on each hot module reload.
-
 ### Adding Examples
 
 To add a course, blog, talk, podcast, or screencast to our docs, submit a
@@ -240,12 +239,13 @@ Each plugin submitted to the plugins list should have the following:
 
 ### Adding Pages
 
-To add a page such as a new guide or API documentation:
+To add a page, such as a new guide or API documentation:
 
 - Add the new page to the relevant directory under [`content`](/content).
 - Link to your new page in the [`sidebar.json`](/content/_data/sidebar.json).
-- Add translations for the sidebar link for each supported language (for
-  English, this is located in [`en.json`](/content/_data/en.json)).
+- Add translations for the sidebar link for each supported language. Currently
+  only English is supported and this is located in
+  [`en.json`](/content/_data/en.json)).
 - 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
@@ -265,18 +265,6 @@ To add a page such as a new guide or API documentation:
 > specific layout I want to create. The page will then be accessible at the
 > route `/guides/my-dashboard-guide`.
 
-### Deleting Pages
-
-To delete a page:
-
-- Delete the page from the relevant directory under [`content`](/content).
-- Remove the link from the the [`sidebar.json`](/content/_data/sidebar.json).
-- **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
@@ -289,10 +277,10 @@ API documentation for commands is in the
 2. Write the document. Look to the existing documentation to see how to
    structure the content.
 3. Open the [`content/_data/sidebar.json`](/content/_data/sidebar.json) 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` section.
+   add a link the new `privatestate` page. In this example, we're adding a
+   command, so we'll add a link underneath the `api` section.
 
-```json
+```diff
 "api": [
   {
     "title": "API",
@@ -311,10 +299,10 @@ API documentation for commands is in the
             "slug": "as"
           },
           // ...
-          {
-            "title": "privateState",
-            "slug": "privatestate"
-          }
++         {
++           "title": "privateState",
++           "slug": "privatestate"
++         }
         ]
       }
     ]
@@ -374,46 +362,33 @@ a menu structure up to three (3) levels deep:
 ]
 ```
 
-4. Submit a [pull request](#Pull-Requests) for your change.
-
-### Writing the Changelog
-
-When adding to the Changelog, create a new file in
-[`content/_changelogs`](/content/_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`](https://github.com/cypress-io/cypress) repo and link to that issue
-(except for Documentation changes).
+### Deleting Pages
 
-#### Categories
+To delete a page:
 
-- **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
+- Delete the page from the relevant directory under [`content`](/content).
+- Remove the link from the the [`sidebar.json`](/content/_data/sidebar.json).
+- **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.
 
 ## Committing Code
 
-### Linting
-
-Javascript code is linted with [ESLint](https://eslint.org/).
-
 ### 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 `master` branch in
-  `cypress-io/cypress-documentation`
+- The PR should be from your repository to the appropriate branch in the
+  `cypress-io/cypress-documentation` repository.
+  - For documation changes that are not tied to a feature release, open a PRs
+    against the `master` branch.
+  - For documentation additions for unreleased features, open a PR against the
+    corrsponding `X.Y.Z-release` branch. Once the release it performed, this
+    branch will be merged into master by the releaser.
 - When opening a PR for a specific issue already open, please use the
   `closes #issueNumber` syntax in the pull request description&mdash;for
   example, `closes #138`&mdash;so that the issue will be
@@ -436,6 +411,30 @@ open a pull request (PR) from your repo to the
   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`.
 
+### Writing the Changelog
+
+When adding to the Changelog, create a new file in
+[`content/_changelogs`](/content/_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`](https://github.com/cypress-io/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
+
 ### Contributor License Agreement
 
 We use a [`cla-assistant.io`](https://cla-assistant.io/) web hook to make sure

content/_changelogs/8.5.0.md

@@ -27,4 +27,6 @@ _Released 09/27/2021_
   Windows 32-bit OS. See
   [#17962](https://github.com/cypress-io/cypress/issues/17962) for more detail.
   Addresses [#18094](https://github.com/cypress-io/cypress/issues/18094).
-- Improved the error messages when an invalid argument type is passed to the [`.select()`](/api/commands/select) command. Addressed in [#18234](https://github.com/cypress-io/cypress/pull/18234).
+- Improved the error messages when an invalid argument type is passed to the
+  [`.select()`](/api/commands/select) command. Addressed in
+  [#18234](https://github.com/cypress-io/cypress/pull/18234).

content/_changelogs/8.6.0.md

@@ -26,8 +26,9 @@ _Released 10/11/2021_
 - The Cypress App will no longer crash when passed a `--spec: {}` from the CLI
   and instead error when passed an invalid object argument. Fixes
   [#3957](https://github.com/cypress-io/cypress/issues/3957).
-- Logging a plain object no longer results in the error "Cannot convert object 
-  to primitive value". Fixes [#18143](https://github.com/cypress-io/cypress/issues/18143).
+- Logging a plain object no longer results in the error "Cannot convert object
+  to primitive value". Fixes
+  [#18143](https://github.com/cypress-io/cypress/issues/18143).
 
 **Misc:**
 

content/_data/webinars.json

@@ -163,4 +163,4 @@
       "slides": "https://slides.com/bahmutov/cy-parallelization"
     }
   ]
-}
+}