From 1ee2837d6286a7d24af818c63ed06e6ef35b9b0b Mon Sep 17 00:00:00 2001 From: Jirka Borovec Date: Sat, 18 Apr 2020 00:17:33 +0200 Subject: [PATCH] add QA to docs (#1374) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add QA to docs * not about doc updates by @awaelchli * Apply suggestions from code review Co-Authored-By: Adrian Wälchli * help Co-authored-by: Adrian Wälchli --- .github/CONTRIBUTING.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6069d720a7..c7df9af637 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -110,6 +110,17 @@ def my_func(param_a: int, param_b: Optional[float] = None) -> str: return str(param_a + p) ``` +When updating the docs make sure to build them first locally and visually inspect the html files (in the browser) for +formatting errors. In certain cases, a missing blank line or a wrong indent can lead to a broken layout. +Run these commands +```bash +cd docs +pip install -r requirements.txt +make html +``` +and open `docs/build/html/index.html` in your browser. + + ### Testing Test your work locally to speed up your work since so you can focus only in particular (failing) test-cases. @@ -145,3 +156,29 @@ We welcome any useful contribution! For convinece here's a recommended workflow: 4. Use tags in PR name for following cases: - **[blocked by #]** if you work is depending on others changes - **[wip]** when you start to re-edit your work, mark it so no one will accidentally merge it in meantime + +### Question & Answer + +1. **How can I help/contribute?** + + All help is very welcome - reporting bug, solving issues and preparing bug fixes. To solve some issues you can start with label [good first issue](https://github.com/PyTorchLightning/pytorch-lightning/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or chose something close to your domain with label [help wanted](https://github.com/PyTorchLightning/pytorch-lightning/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). Before you start to implement anything check that the issue description that it is clear and self-assign the task to you (if it is not possible, just comment that you take it and we assign it to you...). + +2. **Is there a recommendation for branch names?** + + We do not rely on the name convention so far you are working with your own fork. Anyway it would be nice to follow this convention `/_` where the types are: `bugfix`, `feaure`, `docs`, `tests`, ... + +3. **How to rebase my PR?** + + We recommend to create a PR in separate branch different from `master`, especially if you plan to submit several changes and do not want to wait until the fist one is resolved (we can work on them in parallel). Update your master with upstream (assuming you have already set [upstream](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork)) + ```bash + git fetch --all --prune + git checkout master + git merge upstream/master + ``` + checkout your feature branch + ```bash + git checkout my-PR-branch + git rebase master + # follow git instructions to resolve conflists + git push -f + ```