Skip to content

Commit

Permalink
Improve meta documents (OWASP#240)
Browse files Browse the repository at this point in the history 
* Improve meta documents

- Add Style Guide
- Clarify contributing instructions
- Introduce issue naming convention
- Fix up README
- Improve article example and template explanation
- Remove underscores from issue templates since content is viewed as
Markdown

* Fix linting
* Add etc, ellipsis, and ex
* Add Twitter links
* chore: article to template usage
  • Loading branch information
@victoriadrake @ThunderSon
victoriadrake authored and ThunderSon committed Dec 21, 2019
1 parent eef0ecd commit 8791969
Show file tree
Hide file tree
Showing 13 changed files with 459 additions and 216 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ assignees: ''
---

**What would you like to happen?**
_Add a clear and concise description of your idea to improve the project._
Add a clear and concise description of your idea to improve the project.
6 changes: 3 additions & 3 deletions .github/ISSUE_TEMPLATE/fix-request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ assignees: ''
---

**What's the issue?**
_Describe the problem and why it should be fixed. Be concise and specific. Reference sections where appropriate._
Describe the problem and why it should be fixed. Be concise and specific. Reference sections where appropriate.

**How do we solve it?**
_Clearly describe the solution you'd like to see implemented._
Clearly describe the solution you'd like to see implemented.

Would you like to be assigned to this issue?
_Check the box if you will submit a PR to fix this issue. Please read CONTRIBUTING.md._
Check the box if you will submit a PR to fix this issue. Please read CONTRIBUTING.md.
- [ ] Assign me, please!
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/new-content.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ assignees: ''
---

**What would you like added?**
_Briefly describe the topic of the new content. Is this a new section or an addition to an existing topic?_
Briefly describe the topic of the new content. Is this a new section or an addition to an existing topic?

Would you like to be assigned to this issue?
_Check the box if you will submit a PR to add the proposed content. Please read CONTRIBUTING.md._
Check the box if you will submit a PR to add the proposed content. Please read CONTRIBUTING.md.
- [ ] Assign me, please!
96 changes: 36 additions & 60 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,88 +1,64 @@
# Contributing to the Testing Guide

The team thanks you for considering contributing to the project!
Thank you for considering contributing to the Web Security Testing Guide (WSTG)!

The guidelines mentioned below will help you to contribute in a manner to conform to the project's rules, which makes all contributions uniform, and allows the reviewing team to review in a faster manner. If you feel like what you are working on breaks a rule, and that rule needs to be broken as a necessity for that contribution, kindly use your best judgement. If you feel like this document can be improved in any manner, send us a pull request and it will be taken into consideration.
This document explains how to make a helpful contribution.

## How to Contribute

Other than what is discussed in the below sections, you can check out the Open Source Guide for [why and how to contribute](https://opensource.guide/how-to-contribute/).
Here are two ways you can contribute to the guide. You will need a [GitHub account](https://help.github.com/en/github/getting-started-with-github/signing-up-for-a-new-github-account) in order to help out.

### Issues in the Testing Guide
The [Open Source Guide for why and how to contribute](https://opensource.guide/how-to-contribute/) is also a good resource.

This section guides you through reporting issues in the existing project content. These issues can range from, and are not restricted to the below list:
### 1. Tell Us How to Improve

- Grammar mistakes.
- Lacking enough details to achieve a full attack.
- Deprecated attack implementation that no longer works.
[Create an issue](https://github.com/OWASP/wstg/issues/new/choose) using the appropriate template.

In order to report an issue:
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.

Create an [issue](https://github.com/OWASP/OWASP-Testing-Guide-v5/issues) using the [fix request template](https://github.com/OWASP/OWASP-Testing-Guide-v5/issues/new?assignees=&labels=QA%2FEdit&template=fix-request.md&title=)
### 2. Make an Improvement Yourself

In order to fix an [issue](https://github.com/OWASP/OWASP-Testing-Guide-v5/issues), follow the guidance of [how to send a PR](#how-to-send-a-PR).
Here are the steps for creating and submitting a Pull Request (PR) that we can quickly review and merge.

### Creating New Testing Scenarios
1. [Set up your environment](#how-to-set-up-your-contributor-environment) to fork the project and install a Markdown linter.
2. Associate your contribution with an [issue](https://github.com/OWASP/wstg/issues). To change existing content, read [Improve Existing Content](#improve-existing-content). To make additions, read [Add New Content](#add-new-content).
3. Make your modifications. Be sure to follow our [style guide](style_guide.md).
4. When you're ready to submit your work, push your changes to your fork. Ensure that your fork is [synced with `master`](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork), then [create a PR](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). You may want to [allow edits from maintainers](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so we can help with small changes like fixing typos.
5. We'll review your PR. We may comment to ask for clarification or changes, so please check back in the next few days.

This section guides you through providing new content to the testing guide. When adding new content, please follow the [template materials](https://github.com/OWASP/wstg/tree/master/template).
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](document/1_Frontispiece/1_Frontispiece.md).

New content can be:
#### Improve Existing Content

- New methods to test against a certain weakness.
- New techniques or details to test against a newly discovered weakness.
Keeping the project up to date and looking spiffy is a group effort! The WSTG is a constantly updated document. 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](template) and [style guide](style_guide.md).

In order to suggest a new scenario, follow the guidance of [how to send a PR](#how-to-send-a-PR).
We greatly appreciate your help with updating content, and fixing errors including spelling and grammar.

### How to Send a PR
To help us keep track of your work, associate your contribution with an issue:

- Make sure that you have properly [setup your environment](#how-to-set-up-my-contributor-environment).
- Fork the repository by using the Fork button in our [repository](https://github.com/OWASP/OWASP-Testing-Guide-v5).
- If you have a fork that is behind from master, make sure that you [sync your fork](https://help.github.com/en/articles/syncing-a-fork) first.
1. Choose an [open and unassigned issue](https://github.com/OWASP/wstg/issues?q=is%3Aopen+is%3Aissue+no%3Aassignee) to work on, or [open an issue](https://github.com/OWASP/wstg/issues/new/choose) 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`.

#### Create a New Branch
#### Add New Content

```bash
# Checkout the master branch to be sure that your new branch is coming from master
git checkout master
The OWASP Testing Guide would not be possible without the contributions of the security community. Whether you are submitting a new section or adding information to an existing one, please follow the [template example](template/999.1_Testing_for_a_Cat_in_a_Box_OTG-FOO-001.md). The [template sections are explained here](template/999.2_Template_Explanation_OTG-FOO-002.md).

# Create a new branch such as OTG-96
git branch OTG-[issue number]
To help us keep track of your work, associate your contribution with an issue:

# Switch to your new branch
git checkout OTG-[issue number]
```
1. Open an [Add New Content issue](https://github.com/OWASP/wstg/issues/new?assignees=&labels=New&template=new-content.md&title=), or choose an [unassigned new content issue](https://github.com/OWASP/wstg/issues?q=is%3Aopen+is%3Aissue+label%3ANew+no%3Aassignee) 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`.

Now, you can go high and low with your commits and contributions.
## How to Set Up Your Contributor Environment

#### Submit the New Branch
1. [Create an account on GitHub](https://help.github.com/en/github/getting-started-with-github/signing-up-for-a-new-github-account).
2. Install [Visual Studio Code](https://code.visualstudio.com/) and this [Markdown linter plugin](https://github.com/DavidAnson/vscode-markdownlint#install). We use this linter to help keep the project content consistent and pretty.
3. Fork and clone your own copy of the repository. Here are complete instructions for [forking and syncing with GitHub](https://help.github.com/en/github/getting-started-with-github/fork-a-repo).

Once done, you should submit your work to the main repository.
## How to Submit a Good PR

```bash
# Push all your changes to your repository
git push origin
```
To increase the chances that your PR is merged, please make sure that:

Now you can safely go and create a new pull request from your repository.

At the PR submission, take into account reviewer's comments.

To update your work based on the reviews, simply create new commits on the branch you created and push them to your repository.

Once accepted, your name will be added to the project authors.

### How to Set Up My Contributor Environment

1. [Join GitHub](https://github.com/join).
2. Install [Visual Studio Code](https://code.visualstudio.com/).
3. Install the following [markdown linter plugin](https://github.com/DavidAnson/vscode-markdownlint#install).
4. You can safely follow now [how to send a PR](#how-to-send-a-pr).

#### How to Run Local CI Tests

1. Go to the project folder in your terminal
2. Make sure you have installed [node](https://nodejs.org)
3. Install node modules
`npm install`
4. Run test
`npm test`
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](template) and [style guide](style_guide.md).
4. Your code snippets are correct, well-tested, and commented where necessary for understanding.
97 changes: 28 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,84 +1,49 @@
# OWASP Testing Guide Project
# OWASP Web Security Testing Guide

[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/OWASP/OWASP-Testing-Guide-v5/issues)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/OWASP/wstg/issues)
[![OWASP Flagship](https://img.shields.io/badge/owasp-flagship-brightgreen.svg)](https://www.owasp.org/index.php/OWASP_Project_Inventory#tab=Flagship_Projects)
![Twitter Follow](https://img.shields.io/twitter/follow/owasp_wstg?style=social)

Welcome to the OWASP Testing Guide (OTG) project!
[![Creative Commons License](https://licensebuttons.net/l/by-sa/4.0/88x31.png)](https://creativecommons.org/licenses/by-sa/4.0/ "CC BY-SA 4.0")

You can download the stable version v4 [here](http://www.owasp.org/index.php/OWASP_Testing_Project).
Welcome to the official repository for the Open Web Application Security Project (OWASP) Web Security Testing Guide (WSTG). The WSTG is a comprehensive guide to testing the security of web applications and web services. Created by the collaborative efforts of security professionals and dedicated volunteers, the WSTG provides a framework of best practices used by penetration testers and organizations all over the world.

1. [OWASP Testing Guide Project](#owasp-testing-guide-project)
1. [Contributions, Feature Requests, and Feedback](#contributions-feature-requests-and-feedback)
2. [Style Guidelines](#style-guidelines)
3. [Maintainers](#maintainers)
4. [Special Thanks](#special-thanks)
5. [Project Summit 2017 Outcomes](#project-summit-2017-outcomes)
We are currently working on release version 5.0. You can [read the current document here on GitHub](https://github.com/OWASP/wstg/tree/master/document).

## Contributions, Feature Requests, and Feedback

**Everyone can contribute!** By simply reading the document, which you certainly should do, grammar mistakes, new ideas, or paragraph restructuring thoughts will show themselves! Just try it out, you'll see. :smile:

Not to mention, you'll be on the authors, or reviewers and editors list.

Before you start contributing, please read our [**contribution guide**](CONTRIBUTING.md) and [**template**](template/999.2_Template_Explanation_OTG-FOO-002.md) which should help you get started and follow our best practices.
For the last stable release, [view the previous version 4.0](http://www.owasp.org/index.php/OWASP_Testing_Project).

Whenever you identify a contribution possibility, open up an [issue](https://github.com/OWASP/OWASP-Testing-Guide-v5/issues) with it in order for us to keep track and assign project milestones.
- [OWASP Web Security Testing Guide](#owasp-web-security-testing-guide)
- [Contributions, Feature Requests, and Feedback](#contributions-feature-requests-and-feedback)
- [Chat With Us](#chat-with-us)
- [Maintainers](#maintainers)
- [Special Thanks](#special-thanks)

For the ones that enjoy providing constructive feedback and feel like they can review other's contributions, head straight to our [Pull Requests](https://github.com/OWASP/OWASP-Testing-Guide-v5/pulls)!
## Contributions, Feature Requests, and Feedback

Despite us being technical, we love having technical and casual chats with others. Join us by following the below steps:
We are actively inviting new contributors! To start, read the [contribution guide](CONTRIBUTING.md).

- Join [OWASP Slack](https://join.slack.com/t/owasp/shared_invite/enQtNjExMTc3MTg0MzU4LWQ2Nzg3NGJiZGQ2MjRmNzkzN2Q4YzU1MWYyZTdjYjA2ZTA5M2RkNzE2ZjdkNzI5ZThhOWY5MjljYWZmYmY4ZjM).
- Join this project's [channel: #testing-guide](https://app.slack.com/client/T04T40NHX/CJ2QDHLRJ) (yes, you can join other channels, we won't stop you!).
This project is only possible thanks to the work of many dedicated volunteers. Everyone is encouraged to help in ways large and small. Here are a few ways you can help:

Feel free to ask questions, bounce ideas off us, or just hang out and chat!
- Read the current content and help us fix any spelling mistakes or grammatical errors.
- Choose an existing issue and submit a pull request to fix it.
- Open a new issue to report an opportunity for improvement.

You can also open up a post on our [Google Group](https://groups.google.com/a/owasp.org/forum/#!forum/testing-guide-project)!
To learn how to contribute successfully, read the [contribution guide](CONTRIBUTING.md).

## Style Guidelines
Successful contributors appear on [the project's list of authors, reviewers, or editors](document/1_Frontispiece/1_Frontispiece.md).

- Please refer to the [template materials](https://github.com/OWASP/wstg/tree/master/template) when adding content.
- Please don't write in the first person (Ex: no "I" or "Me" statements).
- Please do use Title Caps for headings, using Title Capitalization as defined by the *Chicago Manual of Style*. For quick reference you can use this [online tool](https://capitalizemytitle.com/#Chicago) (make sure you select the "Chicago" tab).
- Please do use serial or [Oxford commas](https://www.grammarly.com/blog/what-is-the-oxford-comma-and-why-do-people-care-so-much-about-it/).
- Don't use `and/or`. Chances are you can simply write `or`. (Note: The OR allows for the same True result as an AND, while also allowing for other combinations producing True results.) Unless you actually mean something like "A and/exclusive or B" in which case read the sentence to yourself with those words and then figure out a different way to write it. :smile:
- Caption figures using title case, with the section and sub-section numbers, followed by the figure position in the document. Use the format *`Figure <section>.<sub-section>-<position>: Caption Title`*. For example, the first image shown in section 4.8, sub-section 19 would be added as follows:
## Chat With Us

```md
![SSTI XVWA Example](images/SSTI_XVWA.jpeg)\
*Figure 4.8.19-1: SSTI XVWA Example*
```
We're easy to find on Slack:

## Project Folder Structure
1. Join the OWASP Group Slack with this [invitation link](https://join.slack.com/t/owasp/shared_invite/enQtNjExMTc3MTg0MzU4LWQ2Nzg3NGJiZGQ2MjRmNzkzN2Q4YzU1MWYyZTdjYjA2ZTA5M2RkNzE2ZjdkNzI5ZThhOWY5MjljYWZmYmY4ZjM).
2. Join this project's [channel, #testing-guide](https://app.slack.com/client/T04T40NHX/CJ2QDHLRJ).

When adding articles and images, please place articles in the appropriate sub-section directory, and place images in an `images/` folder within the article directory. Here is an example of the project structure:
Feel free to ask questions, suggest ideas, or share your best recipes.

```console
document/
├───0_Foreword/
│ └───0_Foreword.md
├───1_Frontispiece/
│ ├───images/
│ │ └───example.jpg
│ └───1_Frontispiece.md
├───2_Introduction/
│ ├───images/
│ │ └───example.jpg
│ └───2_Introduction.md
├───3_The_OWASP_Testing_Framework/
│ ├───images/
│ │ └───example.jpg
│ └───3_The_OWASP_Testing_Framework.md
├───4_Web_Application_Security_Testing/
│ ├───4.1_Introduction_and_Objectives/
│ │ └───4.1_Testing_Introduction_and_Objectives.md
│ ├───4.2_Information_Gathering/
│ │ ├───images/
│ │ │ └───example.jpg
│ │ ├───4.2_Testing_Information_Gathering.md
│ │ └───4.2.1_Conduct_Search_Engine_Discovery.md
You can @ us on Twitter [@owasp_wstg](https://twitter.com/owasp_wstg).

```
You can also join our [Google Group](https://groups.google.com/a/owasp.org/forum/#!forum/testing-guide-project).

## Maintainers

Expand All @@ -87,10 +52,4 @@ document/

## Special Thanks

For the people that helped migrate this project from MediaWiki to GitHub's flavored Markdown, thank you!

- [Rejah Rehim](https://github.com/rejahrehim)

## Project Summit 2017 Outcomes

The outcomes can be found [here](OWASP_Summit_Outcomes.md)
- [Rejah Rehim](https://github.com/rejahrehim) for your help to migrate this project from MediaWiki to GitHub Flavored Markdown.
6 changes: 3 additions & 3 deletions document/1_Frontispiece/1_Frontispiece.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# OWASP Testing Guide 5.0
# OWASP Web Security Testing Guide 5.0

## Welcome

Expand All @@ -14,7 +14,7 @@ Copyright (c) 2019 The OWASP Foundation.

This document is released under the [Creative Commons 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/). Please read and understand the license and copyright conditions.

## v5 Authors
## Authors

- Janos Zold
- Manh Pham Tien
Expand All @@ -23,7 +23,7 @@ This document is released under the [Creative Commons 4.0 License](https://creat
- Tal Argoni
- Victoria Drake

## v5 Reviewers/Editors
## Reviewers or Editors

- Asharaf Ali
- Elie Saad
Expand Down
Loading

0 comments on commit 8791969

Please sign in to comment.