From ac72ad96ede09221f24e2138b05d982066b351a7 Mon Sep 17 00:00:00 2001 From: Dexter Date: Mon, 12 Aug 2024 12:09:23 -0700 Subject: [PATCH] feat: improve onboarding of contributors (#132) * feat: refine README * feat: reference contribution guideline * feat: add .gitignore * feat: add PR template --- .github/pull_request_template.md | 9 +++++++ .gitignore | 3 +++ CONTRIBUTING.md | 3 +++ README.md | 41 ++++++++++++-------------------- 4 files changed, 30 insertions(+), 26 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..b59f1e75 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,9 @@ +## Proposed changes + +Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request. If it fixes a bug or resolves a feature request, be sure to link to that issue. + + + +## Further comments + + \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..bce10a09 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +public/* +.hugo_build.lock +.vscode/* \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..65dd5182 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contribution Guidelines + +Please refer to [contribution_guidelines.md](content/development/contribution_guidelines.md). \ No newline at end of file diff --git a/README.md b/README.md index 9ec51522..ac0be45a 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,39 @@ # CRS Documentation Repository -This repository contains the documentation for OWASP CRS. +This repository contains the documentation for OWASP CRS. For the official website, see [https://coreruleset.org/](https://coreruleset.org/). -## For users of the CRS +## For Readers -The generated documentation is automatically updated at https://coreruleset.org/docs/. If you just want to read the documentation, you can find it there. If you intend to _contribute_ to the documentation, the rest of this page will guide you through it. +The generated documentation is automatically updated at https://coreruleset.org/docs/. If you just want to read the documentation, you can find it there. -## Requirements +## For Contributors -You can edit the documentation on your local system. The only thing you need is the latest [Hugo binary](https://gohugo.io/getting-started/installing/) for your OS (Windows, Linux, Mac): it’s that simple. +Welcome! This page will guide you through the process of contributing to the CRS documentation. Before you start, please read our [Contribution Guideline](content/development/contribution_guidelines.md). -**Important: You need Hugo _extended_ version >= 0.93.0.** +### 1. Prerequisites -## Cloning this repository +To contribute to the CRS documentation, the only thing you need is the latest [Hugo binary](https://gohugo.io/getting-started/installing/) for your OS (Windows, Linux, Mac) **(Important: You need Hugo _extended_ version >= 0.93.0.)**. -After getting hugo, just clone this repository to work locally. This way you can edit and verify quickly that everything is working properly before creating a new pull request. +### 2. Building the Local Environment -To clone, use the *recursive* option so you will be getting also the theme to render the pages properly: +Once you have Hugo, clone this repository to work locally. You can edit and verify quickly that everything is working properly before creating a new pull request. +To clone, use the *recursive* option to get the theme we use for the documentation to render the pages properly: ```bash git clone --recursive git@github.com:coreruleset/documentation.git ``` -## Editing locally +Now you have all in place to perform your local edits. Everything is created using [Markdown](https://www.markdownguide.org/), and you will normally use the `content` subdirectory to add your edits. The theme has many shortcodes and others that you can use to simplify editing. You can get more information about it on [Hugo Relearn theme](https://themes.gohugo.io/themes/hugo-theme-relearn/). -Now you have all in place to perform your local edits. - -Everything is created using markdown, and you will normally use the `content` subdirectory to add your edits. - -The theme has many shortcodes and others that you can use to simplify editing. You can get more information about it on [Hugo Relearn theme](https://themes.gohugo.io/themes/hugo-theme-relearn/). - -You can run `hugo` to serve the pages, and while you edit and save, your changes will be refreshed in the browser! +Now, you can run `hugo` to serve the pages, and while you edit and save, your changes will be refreshed in the browser! Use: -``` +```bash hugo serve ``` Then check your edits on http://localhost:1313/documentation/. -## Creating a pull request - -If you are a CRS developer, you can make a branch in the documentation repository. - -If you are an outside contributor, you can fork the [repository](https://github.com/coreruleset/documentation/) to your own GitHub account and create a branch in your fork. - -Once you are happy with your changes, [send a PR](https://github.com/coreruleset/documentation/pulls) with your changes. +### 3. Creating a Pull Request -After review and merging, the documentation is built and published on [https://coreruleset.org/docs](https://coreruleset.org/docs/) after max. 5 minutes. +If you are a CRS developer, you can make a branch in the documentation repository. If you are an outside contributor, you can fork the [repository](https://github.com/coreruleset/documentation/) to your own GitHub account and create a branch in your fork. Once you are happy with your changes, [send a PR](https://github.com/coreruleset/documentation/pulls) with your changes. After review and merging, the documentation is built and published on [https://coreruleset.org/docs](https://coreruleset.org/docs/) after max. 5 minutes.