|
| 1 | +# Contributing Guide |
| 2 | + |
| 3 | +Thanks for your interest in contributing to `rate-limit-postgresql`! This guide |
| 4 | +will show you how to set up your environment and contribute to this library. |
| 5 | +This contributing guide is inspired by the |
| 6 | +[rate-limit-redis contributing guide](https://github.com/express-rate-limit/rate-limit-redis/blob/main/contributing.md) |
| 7 | + |
| 8 | +## Set Up |
| 9 | + |
| 10 | +First, you need to install and be familiar the following: |
| 11 | + |
| 12 | +- `git`: [Here](https://github.com/git-guides) is a great guide by GitHub on |
| 13 | + installing and getting started with Git. |
| 14 | +- `node` and `npm`: |
| 15 | + [This guide](https://nodejs.org/en/download/package-manager/) will help you |
| 16 | + install Node and npm. The recommended method is using the `nvm` version |
| 17 | + manager if you are on MacOS or Linux. Make sure you are using the |
| 18 | + [active LTS version](https://github.com/nodejs/Release#release-schedule) of |
| 19 | + Node. |
| 20 | + |
| 21 | +Once you have installed the above, follow |
| 22 | +[these instructions](https://docs.github.com/en/get-started/quickstart/fork-a-repo) |
| 23 | +to |
| 24 | +[`fork`](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks) |
| 25 | +and [`clone`](https://github.com/git-guides/git-clone) the repository |
| 26 | +(`adrianprelipcean/express-rate-limit-postgresql`). |
| 27 | + |
| 28 | +Once you have forked and cloned the repository, you can |
| 29 | +[pick out an issue](https://github.com/adrianprelipcean/express-rate-limit-postgresql/issues) |
| 30 | +you want to fix/implement! |
| 31 | + |
| 32 | +## Making Changes |
| 33 | + |
| 34 | +Once you have cloned the repository to your computer (say, in |
| 35 | +`~/Code/rate-limit-postgresql`) and picked the issue you want to tackle, create |
| 36 | +a branch: |
| 37 | + |
| 38 | +```sh |
| 39 | +> git checkout -b branch-name |
| 40 | +``` |
| 41 | + |
| 42 | +While naming your branch, try to follow the below guidelines: |
| 43 | + |
| 44 | +1. Prefix the branch name with the type of change being made: |
| 45 | + - `fix`: For a bug fix. |
| 46 | + - `feat`: For a new feature. |
| 47 | + - `test`: For any change related to tests. |
| 48 | + - `perf`: For a performance related change. |
| 49 | + - `meta`: Anything related to the build process, workflows, issue templates, |
| 50 | + etc. |
| 51 | + - `refc`: For any refactoring work. |
| 52 | + - `docs`: For any documentation related changes. |
| 53 | +2. Make the branch name short but self-explanatory. |
| 54 | + |
| 55 | +Once you have created a branch, you can start coding! |
| 56 | + |
| 57 | +The library is written in |
| 58 | +[Typescript](https://github.com/microsoft/TypeScript#readme) and |
| 59 | +[supports the 16+ LTS versions](https://github.com/nodejs/Release#release-schedule) |
| 60 | +of Node. The code is arranged as follows: |
| 61 | + |
| 62 | +```sh |
| 63 | +rate-limit-postgresql |
| 64 | +├── changelog.md |
| 65 | +├── code_of_conduct.md |
| 66 | +├── configs |
| 67 | +│ ├── tsconfig.base.json |
| 68 | +│ ├── tsconfig.cjs.json |
| 69 | +│ └── tsconfig.esm.json |
| 70 | +├── contributing.md |
| 71 | +├── license.md |
| 72 | +├── package.json |
| 73 | +├── package-lock.json |
| 74 | +├── readme.md |
| 75 | +├── source |
| 76 | +│ ├── index.ts |
| 77 | +│ ├── migrations |
| 78 | +│ │ └── 1-init.sql |
| 79 | +│ ├── models |
| 80 | +│ │ └── session.ts |
| 81 | +│ ├── stores |
| 82 | +│ │ ├── aggregated_ip |
| 83 | +│ │ │ └── store_aggregated_ip.ts |
| 84 | +│ │ └── individual_ip |
| 85 | +│ │ └── store_individual_ip.ts |
| 86 | +│ └── util |
| 87 | +│ ├── migration_handler.ts |
| 88 | +│ └── session_handler.ts |
| 89 | +├── test |
| 90 | +│ ├── stores |
| 91 | +│ │ ├── store_aggregated_ip.spec.ts |
| 92 | +│ │ └── store_individual_ip.spec.ts |
| 93 | +│ └── util |
| 94 | +│ └── session_handler.spec.ts |
| 95 | +└── third_party_licenses |
| 96 | + ├── dev_detailed.json |
| 97 | + ├── dev_summary.txt |
| 98 | + ├── production_detailed.json |
| 99 | + └── production_summary.txt |
| 100 | +``` |
| 101 | + |
| 102 | +> The content of `third_party_licenses` is auto-generated. |
| 103 | +
|
| 104 | +If your changes also include database migrations, please review |
| 105 | +(postgres-migrations)[https://www.npmjs.com/package/postgres-migrations] in |
| 106 | +terms of which migrations are supported, their immutability, how are they |
| 107 | +applied, etc. |
| 108 | + |
| 109 | +#### `./` |
| 110 | + |
| 111 | +- `package.json`: Node package information. |
| 112 | +- `package-lock.json`: Node package lock file, please do not modify manually. |
| 113 | +- `changelog.md`: A list of changes that have been made in each version. |
| 114 | +- `contributing.md`: This file, helps contributors get started. |
| 115 | +- `license.md`: Tells people how they can use this package. |
| 116 | +- `readme.md`: The file everyone should read before using the package. Contains |
| 117 | + installation and usage instructions. |
| 118 | + |
| 119 | +#### `./` |
| 120 | + |
| 121 | +- `tsconfig.*.json`: The Typescript configuration files for this project. |
| 122 | + |
| 123 | +#### `source/` |
| 124 | + |
| 125 | +- `source/migrations/*.sql`: Database migrations that are applied by |
| 126 | + `postgres-migrations` `source/models/*.ts`: Relevant types (e.g., Session) |
| 127 | +- `source/util/*.ts`: The centralized business logic for handling session |
| 128 | + validity (`session_handler.ts`) and migration handling |
| 129 | + (`migration_handler.ts`) |
| 130 | +- `source/stores/store_aggregated_ip.ts`: The PostgreSQL stores that aggregates |
| 131 | + the IP count in the table. |
| 132 | +- `source/stores/store_individual_ip.ts`: The PostgreSQL stores that stores the |
| 133 | + IP of each request in a separate row and performs the aggregation at a |
| 134 | + separate step |
| 135 | + |
| 136 | +#### `test/` |
| 137 | + |
| 138 | +- `test/*/*.spec.ts`: Tests a part of the library. |
| 139 | + |
| 140 | +When adding a new feature/fixing a bug, please add/update the readme and |
| 141 | +changelog as well as add tests for the same. Also make sure your code has been |
| 142 | +linted and that existing tests pass. You can run the linter using |
| 143 | +`npm run lint`, the tests using `npm run test` and try to automatically fix most |
| 144 | +lint issues using `npm run lint-autofix`. |
| 145 | + |
| 146 | +Once you have made changes to the code, you will want to |
| 147 | +[`commit`](https://github.com/git-guides/git-commit) (basically, Git's version |
| 148 | +of save) the changes. To commit the changes you have made locally: |
| 149 | + |
| 150 | +```sh |
| 151 | +> git add this/folder that/file |
| 152 | +> git commit --message 'commit-message' |
| 153 | +``` |
| 154 | + |
| 155 | +While writing the `commit-message`, try to follow the below guidelines: |
| 156 | + |
| 157 | +1. Prefix the message with `type:`, where `type` is one of the following |
| 158 | + dependending on what the commit does: |
| 159 | + - `fix`: Introduces a bug fix. |
| 160 | + - `feat`: Adds a new feature. |
| 161 | + - `test`: Any change related to tests. |
| 162 | + - `perf`: Any performance related change. |
| 163 | + - `meta`: Any change related to the build process, workflows, issue |
| 164 | + templates, etc. |
| 165 | + - `refc`: Any refactoring work. |
| 166 | + - `docs`: Any documentation related changes. |
| 167 | +2. Keep the first line brief, and less than 60 characters. |
| 168 | +3. Try describing the change in detail in a new paragraph (double newline after |
| 169 | + the first line). |
| 170 | + |
| 171 | +When you commit files, `husky` and `lint-staged` will automatically lint the |
| 172 | +code and fix most issues. In case an error is not automatically fixable, they |
| 173 | +will cancel the commit. Please fix the errors before committing the changes. |
| 174 | + |
| 175 | +## Contributing Changes |
| 176 | + |
| 177 | +Once you have committed your changes, you will want to |
| 178 | +[`push`](https://github.com/git-guides/git-push) (basically, publish your |
| 179 | +changes to GitHub) your commits. To push your changes to your fork: |
| 180 | + |
| 181 | +```sh |
| 182 | +> git push origin branch-name |
| 183 | +``` |
| 184 | + |
| 185 | +If there are changes made to the `master` branch of the |
| 186 | +`adrianprelipcean/express-rate-limit-postgresql` repository, you may wish to |
| 187 | +[`rebase`](https://docs.github.com/en/get-started/using-git/about-git-rebase) |
| 188 | +your branch to include those changes. To rebase, or include the changes from the |
| 189 | +`master` branch of the `adrianprelipcean/express-rate-limit-postgresql` |
| 190 | +repository: |
| 191 | + |
| 192 | +``` |
| 193 | +> git fetch upstream master |
| 194 | +> git rebase upstream/master |
| 195 | +``` |
| 196 | + |
| 197 | +This will automatically add the changes from `master` branch of the |
| 198 | +`adrianprelipcean/express-rate-limit-postgresql` repository to the current |
| 199 | +branch. If you encounter any merge conflicts, follow |
| 200 | +[this guide](https://docs.github.com/en/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase) |
| 201 | +to resolve them. |
| 202 | + |
| 203 | +Once you have pushed your changes to your fork, follow |
| 204 | +[these instructions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) |
| 205 | +to open a |
| 206 | +[`pull request`](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests): |
| 207 | + |
| 208 | +Once you have submitted a pull request, the maintainers of the repository will |
| 209 | +review your pull requests. Whenever a maintainer reviews a pull request they may |
| 210 | +request changes. These may be small, such as fixing a typo, or may involve |
| 211 | +substantive changes. Such requests are intended to be helpful, but at times may |
| 212 | +come across as abrupt or unhelpful, especially if they do not include concrete |
| 213 | +suggestions on how to change them. Try not to be discouraged. If you feel that a |
| 214 | +review is unfair, say so or seek the input of another project contributor. Often |
| 215 | +such comments are the result of a reviewer having taken insufficient time to |
| 216 | +review and are not ill-intended. Such difficulties can often be resolved with a |
| 217 | +bit of patience. That said, reviewers should be expected to provide helpful |
| 218 | +feedback. |
| 219 | + |
| 220 | +In order to land, a pull request needs to be reviewed and approved by at least |
| 221 | +one maintainer and pass CI. After that, if there are no objections from other |
| 222 | +contributors, the pull request can be merged. |
| 223 | + |
| 224 | +#### Congratulations and thanks for your contribution! |
0 commit comments