Fix docs and add contributing guide (#475)

* fix typo and add example for requestAdaptor.Path * Add contributing guide Co-authored-by: SU Chen <[email protected]> Co-authored-by: Bomin Zhang <[email protected]> Co-authored-by: Yun Long <[email protected]> * Update CONTRIBUTING.md Co-authored-by: Bomin Zhang <[email protected]> * fix typo and add link to contributing.md to README.md Co-authored-by: SU Chen <[email protected]> Co-authored-by: Hao Chen <[email protected]> Co-authored-by: SU Chen <[email protected]> Co-authored-by: Bomin Zhang <[email protected]> Co-authored-by: Yun Long <[email protected]> Co-authored-by: Bomin Zhang <[email protected]> Co-authored-by: Hao Chen <[email protected]>
easegress-io · Jan 27, 2022 · 7fb867a · 7fb867a
1 parent 16a4439
commit 7fb867a
Show file tree

Hide file tree

Showing 3 changed files with 106 additions and 6 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,84 @@
+# Contributing
+
+Welcome to the Easegress contributing guide. Are you looking for help or a way to create bug tickets or discuss new potential features? Perhaps you want to fix a typo in the documentation or are you interested in getting involved in the project? You can find answers to these questions and how to contribute to Easegress in this document.
+
+- [Contributing](#contributing)
+ - [Getting help](#getting-help)
+ - [Feature requests](#feature-requests)
+ - [Reporting general issues](#reporting-general-issues)
+ - [Contributing](#contributing-1)
+ - [Pull request guide](#pull-request-guide)
+
+## Getting help
+
+If you have not already, please check the [README.md](./README.md#getting-started) and the Easegress [documentation](./doc/README.md#easegress-documentation). If you don’t find an answer to your problem, you can ask your question at [Slack](./README.md#community) or in other community channels.
+
+## Feature requests
+
+Do you want to suggest an idea for the project? Use this *Feature request* [issue template](https://github.com/megaease/easegress/issues/new?template=feature_request.md) to describe your idea.
+
+## Reporting general issues
+
+There are many scenarios when you could open an issue, including:
+- Feature request
+- Feature proposal (new filter, new object)
+- Feature design
+- Bug found
+- Performance issues
+- Help wanted
+- Documentation out of date
+- Test improvement
+- Any questions on project
+
+Please describe clearly and explicitly your issue. Try to add as many details as you can. You can follow the instructions in the issue ticket to ensure that the issue contains enough background: https://github.com/megaease/easegress/issues/new/choose
+
+## Contributing
+
+All contributions to Easegress are welcome! It does not necessary need to be coding; you can also contribute without coding by
+
+- Reporting a bug
+- Helping other members of the community at Slack channel
+- Fixing a typo in the code
+- Fixing a typo in the documentation
+- Providing your feedback on the proposed features and designs
+- Reviewing Pull Requests
+
+Contributing code, like bug fixes or new features are equally encouraged! Easegress accepts proposals for new Filters and new Objects or any other useful code changes. Here’s incomplete list of possible code contributions:
+
+- New Filter
+- New Object
+- New feature (other than filter or object)
+- Fixing a bug in the code
+- Code refactoring
+- Performance improvement
+- New unit test or improvement of existing test
+
+
+If you’re unsure, whether your code contribution will be beneficial, open a ticket or ask in Slack. You can check the [Developer Guide](./doc/developer-guide.md#developer-guide) to understand the high level architecture and Filter and Object extensions of Easegress.
+
+For any code or documentation change, please read the following Pull request guide.
+
+## Pull request guide
+
+When contributing to Easegress, it’s good idea to follow these steps:
+
+1. If there is no issue yet, create an issue of the fix or improvement
+2. Fork the repository and clone your fork:
+ 1. `git clone https://github.com/<yourusername>/easegress.git`
+3. Track the upstream remote
+ 1. `git remote add upstream https://github.com/megease/easegress.git`
+4. Create your branch, for example
+ 1. `git checkout -b fix/<micro-title>-<issue-number>`
+5. Do your changes and commit them
+ 1. `git commit -am '<descriptive-message>'`
+6. Rebase latest changes from upstream remote.
+ 1. `git checkout main`
+ 2. `git pull --rebase origin main`
+ 3. `git pull --rebase upstream main`
+ 4. `git checkout <your-branch>`
+ 5. `git rebase main`
+7. Push your changes to your branch.
+ 1. `git push -f origin <your-branch>`
+8. You can now open PR. Add a description for your PR.
+
+For code changes, remember to add unit tests. Before opening PR, you can use Makefile entries (`make fmt`, `make test`, `make integration_test`) to run unit tests and formatting. CI runs Revive code analysis that you can install and execute locally following [these instructions](https://github.com/mgechev/revive#installation).
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 - [Easegress](#easegress)
  - [What is Easegress](#what-is-easegress)
  - [Features](#features)
- - [User Cases](#user-cases)
+ - [Use Cases](#use-cases)
  - [Getting Started](#getting-started)
  - [Setting up Easegress](#setting-up-easegress)
  - [Create an HTTPServer and Pipeline](#create-an-httpserver-and-pipeline)
@@ -19,6 +19,7 @@
  - [Documentation](#documentation)
  - [Roadmap](#roadmap)
  - [Community](#community)
+ - [Contributing](#contributing)
  - [License](#license)
 
 ## What is Easegress
@@ -98,7 +99,7 @@ The architecture of Easegress:
  - **Status Codes:** HTTP status codes.
  - **TopN:** sorted by aggregated APIs(only in server dimension).
 
-## User Cases
+## Use Cases
 
 The following examples show how to use Easegress for different scenarios.
 
@@ -319,6 +320,10 @@ See [Easegress Roadmap](./doc/Roadmap.md) for details.
 - [Join Slack Workspace](https://join.slack.com/t/openmegaease/shared_invite/zt-upo7v306-lYPHvVwKnvwlqR0Zl2vveA) for requirement, issue and development.
 - [MegaEase on Twitter](https://twitter.com/megaease)
 
+## Contributing
+
+See [Contributing guide](./CONTRIBUTING.md#contributing).
+
 ## License
 
 Easegress is under the Apache 2.0 license. See the [LICENSE](./LICENSE) file for details.
diff --git a/doc/reference/filters.md b/doc/reference/filters.md
@@ -346,7 +346,7 @@ timeout: 500ms
 
 The RequestAdaptor modifies the original request according to configuration.
 
-The below example configuration adds prefix `/v3` to the request path.
+The example configuration below adds prefix `/v3` to the request path.
 
 ```yaml
 kind: RequestAdaptor
@@ -356,7 +356,7 @@ path:
 ```
 
 
-The below example configuration removes header `X-Version` from all `GET` requests.
+The example configuration below removes header `X-Version` from all `GET` requests.
 
 ```yaml
 kind: RequestAdaptor
@@ -366,6 +366,17 @@ header:
  del: ["X-Version"]
 ```
 
+The example configuration below modifies request path using regular expressions.
+
+```yaml
+kind: RequestAdaptor
+name: request-adaptor-example
+path:
+ regexpReplace:
+ regexp: "^/([a-z]+)/([a-z]+)" # groups /$1/$2 for lowercase alphabet
+ replace: "/$2/$1" # changes the order of groups
+```
+
 ### Configuration
 
 | Name | Type | Description | Required |
@@ -752,7 +763,7 @@ headerMap:
 | replace | string | Replaces request path with the value of this option when specified | No |
 | addPrefix | string | Prepend the value of this option to request path when specified | No |
 | trimPrefix | string | Trims the value of this option if request path start with it when specified | No |
-| regexReplace | [pathadaptor.RegexpReplace](#pathadaptorRegexpReplace) | Revise request path with regular expression | No |
+| regexpReplace | [pathadaptor.RegexpReplace](#pathadaptorRegexpReplace) | Revise request path with regular expression | No |
 
 ### pathadaptor.RegexpReplace
 
@@ -1018,4 +1029,4 @@ The relationship between `methods` and `url` is `AND`.
 | Name | Type | Description | Required |
 | --------- | ------ | ------------------------------------------------------------------------ | -------- |
 | header | string | The HTTP header that contains JSON value | Yes |
-| json | string | The field name to put JSON value into HTTP body | Yes |
+| json | string | The field name to put JSON value into HTTP body | Yes |