diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE index d969343d..d1010108 100644 --- a/.github/PULL_REQUEST_TEMPLATE +++ b/.github/PULL_REQUEST_TEMPLATE @@ -1,7 +1,8 @@ Before submitting a PR please make sure that: 1. You have discussed your solution in an issue and have got an - approval from a maintainer. + approval from a maintainer. See our + [contribution guide](https://github.com/AdguardTeam/AdGuardHome/blob/master/CONTRIBUTING.md). 2. This isn't a localization fix; please send those to our [CrowdIn](https://crowdin.com/project/adguard-applications/en#/adguard-home) @@ -13,8 +14,8 @@ Before submitting a PR please make sure that: Add a short description here. The description should include: 1. Which issue this PR closes (`Closes #NNNN.`) or updates (`Updates - #NNNN.`). + #NNNN.`). Please do not open PRs without filing an issue first. 2. A short description of how the change achieves that. -Do not forget to remove these instructions. +Do not forget to remove these instructions! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ffcda283 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ + # Contributing to AdGuard Home + +If you want to contribute to AdGuard Home by filing or commenting on an issue or +opening a pull request, please follow the instructions below. + + + +## General recommendations + +Please don't: + + * post comments like “+1” or “this”. Use the :+1: reaction on the issue + instead, as this allows us to actually see the level of support for issues. + + * file issues about localization errors or send localization updates as PRs. + We're using [CrowdIn] to manage our translations and we generally update + them before each Beta and Release build. You can learn more about + translating AdGuard products [in our Knowledge Base][kb-trans]. + + * file issues about a particular filtering-rule list misbehaving. These are + tracked through the [separate form for filtering issues][form]. + + * send updates to filtering-rule lists, such as the ones for the Blocked + Services feature or the list of approved filtering-rule lists. We update + them once before each Beta and Release build. + +Please do: + + * follow the template instructions and provide data for reproducing issues. + + * write the title of your issue or pull request in English. Any language is + fine in the body, but it is important to keep the title in English to make + it easier for people and bots to look up duplicated issues. + +[CrowdIn]: https://crowdin.com/project/adguard-applications/en#/adguard-home +[form]: https://link.adtidy.org/forward.html?action=report&app=home&from=github +[kb-trans]: https://kb.adguard.com/en/general/adguard-translations + + + +## Issues + + ### Search first + +Please make sure that the issue is not a duplicate or a question. If it's a +duplicate, please react to the original issue with a thumbs up. If it's a +question, please look through our [Wiki] and, if you haven't found the answer, +post it to the GitHub [Discussions] page. + +[Discussions]: https://github.com/AdguardTeam/AdGuardHome/discussions/categories/q-a +[Wiki]: https://github.com/AdguardTeam/AdGuardHome/wiki + + + + ### Follow the issue template + +Developers need to be able to reproduce the faulty behavior in order to fix an +issue, so please make sure that you follow the instructions in the issue +template carefully. + + + +## Pull requests + + ### Discuss your changes first + +Please discuss your changes by opening an issue. The maintainers should +evaluate your proposal, and it's generally better if that's done before any code +is written. + + + + ### Review your changes for style + +We have a set of [code guidelines][hacking] that we expect the code to follow. +Please make sure you follow it. + +[hacking]: https://github.com/AdguardTeam/CodeGuidelines/blob/master/Go/Go.md + + + + ### Test your changes + +Make sure that it passes linters and tests by running the corresponding Make +targets. For backend changes, it's `make go-check`. For frontend, run +`make js-lint`. + +Additionally, a manual test is often required. While we're constantly working +on improving our test suites, they're still not as good as we'd like them to be.