Skip to content

Latest commit

 

History

History
112 lines (71 loc) · 8.23 KB

CONTRIBUTING.md

File metadata and controls

112 lines (71 loc) · 8.23 KB
Raw

Contributing to the Testing Guide

Thank you for considering contributing to the Web Security Testing Guide (WSTG)!

Here are some ways you can make a helpful contribution. The Open Source Guide for why and how to contribute is also a good resource. You will need a GitHub account in order to help out.

Become an Author

This project would not be possible without the contributions of writers in the security community! Our authors help to keep the WSTG relevant and useful for everyone.

Whether you are submitting a new section or adding information to an existing one, please follow the template example. The template sections are explained here.

When submitting your pull request, authors should link contributions to an issue:

  1. Open an Add New Content issue, or choose an unassigned new content issue and ask to be assigned to it.
  2. Create and switch to a new local branch with the name new-<issue number>. For example, git checkout -b new-164.

Become a Reviewer or Editor

Keeping the project up to date and looking spiffy is a group effort! The WSTG is a constantly updated document and benefits from your technical or editorial review.

When submitting your pull request, reviewers and editors should link contributions to an issue:

  1. Choose an open issue with the help wanted label to work on, or open an issue yourself. Post a comment in the issue and request to be assigned to it.
  2. Create and switch to a new local branch with the name fix-<issue number>. For example, git checkout -b fix-88.

Technical Review

If you have expertise in any topic covered by the WSTG, your technical review is encouraged. Please ensure that articles:

  • Follow the article template materials
  • Follow the style guide
  • Accurately describe vulnerabilities and tests
  • Have appropriate and up-to-date inline links to resources
  • Provide complete and relevant information suitable for an audience with basic technical expertise

Editorial Review

Grammarians assemble! The WSTG welcomes your improvements in the areas of grammar, formatting, word choice, and brevity. All changes should adhere to the style guide.

Please don't hesitate to make as many changes as you see fit, especially if you notice that existing content does not match the article template materials.

Translation

You can help translating the Guide via GitLocalize. Login with a linked GitHub account, translate some content, submit for moderator review, they'll submit Pull Requests. In the end the guide will become available in multiple languages.

If you don't see your language listed amongst those accepting translation then simply open a new issue and the team will be happy to get it setup. Please mention if you're willing to moderate GitLocalize efforts for your language as chances are the core team do not speak your preferred language fluently (if at all).

How to Open an Issue

Create an issue using the appropriate template.

Choose a short, descriptive title. Briefly explain what you think needs changing. Among other things, your suggestions may include grammar or spelling errors, or address insufficient or outdated content.

How to Submit a Pull Request

Here are the steps for creating and submitting a Pull Request (PR) that we can quickly review and merge.

  1. Set up your environment to fork the project and install a Markdown linter.
  2. Associate your contribution with an issue. To change existing content, read Become a Reviewer or Editor. To make additions, read Become an Author.
  3. Make your modifications. Be sure to follow our style guide.
  4. When you're ready to submit your work, push your changes to your fork. Ensure that your fork is synced with master.
  5. You can submit a draft PR or a regular PR. If your work is not yet ready for review and merge, choose a draft PR. When your changes are ready to be reviewed, you can convert to a regular PR. See how to change the stage of a PR for more.

You may want to allow edits from maintainers so we can help with small changes like fixing typos.

Once you've submitted your ready-for-review PR, we'll review it. We may comment to ask for clarification or changes, so please check back in the next few days.

To increase the chances that your PR is merged, please make sure that:

  1. You've followed the guidelines above for associating your work with an issue.
  2. Your work is Markdown linted.
  3. Your writing follows the article template materials and style guide.
  4. Your code snippets are correct, well-tested, and commented where necessary for understanding.

Once the PR is complete, we'll merge it! At that point, you may like to add yourself to the project's list of authors, reviewers, or editors.

How to Set Up Your Contributor Environment

  1. Create an account on GitHub.

  2. Install Visual Studio Code and this Markdown linter plugin. We use this linter to help keep the project content consistent and pretty.

    1. From the gear icon/menu select "Settings".
    2. Select the "Workspace" tab.
    3. Expand "Extensions", and find "markdownlint".
    4. Just below "Markdownlint: config" click the "Edit in settings.json" link.
    5. Add the following:
    "markdownlint.config": {
  "extends": ".github/configs/.markdownlint.json"
}

  3. Fork and clone your own copy of the repository. Here are complete instructions for forking and syncing with GitHub.

Contributing with Codespaces

We've included settings for GitHub Codespaces so you can use a cloud-hosted IDE to contribute to this repository! Our configuration includes Visual Studio Code extensions and markdownlint configuration settings that help to keep work consistent across all our amazing contributors.

Codespaces is currently in limited beta. To learn more, see About Codespaces.

If you have access to the beta, get started by creating a codespace for this repository.