diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..d4c79c2e --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,60 @@ +Please read the "guidelines for contributing" that are linked ^-- just +up there. Also read the FAQ: https://github.com/foosel/OctoPrint/wiki/FAQ. + +This is a bug and feature tracker, please only use it to report bugs +or request features within OctoPrint (not OctoPi, not any OctoPrint +plugins and not unofficial OctoPrint versions). Mark requests with +a [Request] prefix in the title please. Fully fill out the bug reporting +template for bug reports. + +Do not seek support here ("I need help with ..."), that belongs on +the mailing list or the G+ community (both linked in the "guidelines +for contributing" linked above, read it!), NOT here. + +Thank you! + +---- + +#### What were you doing? + +[Please be as specific as possible here. The maintainers will need to reproduce +your issue in order to fix it and that is not possible if they don't know +what you did to get it to happen in the first place. If you encountered +a problem with specific files of any sorts, make sure to also include a link to a file +with which to reproduce the problem.] + +#### What did you expect to happen? + +#### What happened instead? + +#### Branch & Commit or Version of OctoPrint + +[Can be found in the lower left corner of the web interface.] + +#### Printer model & used firmware incl. version + +[If applicable, always include if unsure.] + +#### Browser and Version of Browser, Operating System running Browser + +[If applicable, always include if unsure.] + +#### Link to octoprint.log + +[On gist.github.com or pastebin.com. Always include and never truncate.] + +#### Link to contents of terminal tab or serial.log + +[On gist.github.com or pastebin.com. If applicable, always include if unsure or +reporting communication issues. Never truncate.] + +#### Link to contents of Javascript console in the browser + +[On gist.github.com or pastebin.com or alternatively a screenshot. If applicable - +always include if unsure or reporting UI issues.] + +#### Screenshot(s) showing the problem: + +[If applicable. Always include if unsure or reporting UI issues.] + +I have read the FAQ. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..b4d5c417 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,50 @@ +Thank you for your interest into contributing to OctoPrint, it's +highly appreciated! + +Please make sure you have read the "guidelines for contributing" as +linked just above this form, there's a section on Pull Requests in there +as well that contains important information. + +As a summary, please make sure you have ticked all points on this +checklist: + + * [ ] Your changes are not possible to do through a plugin and relevant + to a large audience (ideally all users of OctoPrint) + * [ ] If your changes are large or otherwise disruptive: You have + made sure your changes don't interfere with current development by + talking it through with the maintainers, e.g. through a + Brainstorming ticket + * [ ] Your PR targets OctoPrint's devel branch (not master, + maintenance or anything else) + * [ ] Your PR was opened from a custom branch on your repository + (no PRs from your version of master, maintenance or devel please), + e.g. dev/my_new_feature + * [ ] Your PR only contains relevant changes: no unrelated files, + no dead code, ideally only one commit - rebase your PR if necessary! + * [ ] Your changes follow the coding style + * [ ] If your changes include style sheets: You have modified the + .less source files, not the .css files (those are generated with + lessc) + * [ ] You have tested your changes (please state how!) - ideally you + have added unit tests + * [ ] You have run the existing unit tests against your changes and + nothing broke + * [ ] You have added yourself to the AUTHORS.md file :) + +Feel free to delete all this help text, then describe +your PR further. You may use the template provided below to do that. +The more details the better! + +---- + +#### What does this PR do and why is it necessary? + +#### How was it tested? How can it be tested by the reviewer? + +#### Any background context you want to provide? + +#### What are the relevant tickets if any? + +#### Screenshots (if appropriate) + +#### Further notes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c8080f0..2ece77e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -232,43 +232,67 @@ See [How to open the Javascript Console in different browsers](https://webmaster implement your feature as a plugin, create a "Brainstorming" ticket to get the discussion going on how best to solve *this* in OctoPrint's plugin system - maybe that's the actual PR you have been waiting for to contribute :) -2. If you plan to make **any large changes to the code or appearance, please - open a "Brainstorming" ticket first** so that we can determine if it's a - good time for your specific pull request. It might be that we're currently - in the process of making heavy changes to the code locations you'd target - as well, or your approach doesn't fit the general "project vision", and - that would just cause unnecessary work and frustration for everyone or +2. If you plan to make **any large or otherwise disruptive changes to the + code or appearance, please open a "Brainstorming" ticket first** so + that we can determine if it's a good time for your specific pull + request. It might be that we're currently in the process of making + heavy changes to the code locations you'd target as well, or your + approach doesn't fit the general "project vision", and that would + just cause unnecessary work and frustration for everyone or possibly get the PR rejected. 3. Create your pull request **from a custom branch** on your end (e.g. `dev/myNewFeature`)[1] **against the `devel` branch**. Create **one pull request per feature/bug fix**. If your PR contains an important bug fix, we will make sure to backport it to the `maintenance` branch to also include it in the next release. -4. Make sure you **follow the current coding style**. This means: - +4. Make sure there are **only relevant changes** included in your PR. No + changes to unrelated files, no additional files that don't belong (e.g. + commits of your full virtual environment). Make sure your PR consists + **ideally of only one commit** (use git's rebase and squash functionality). +5. Make sure you **follow the current coding style**. This means: * Tabs instead of spaces in the Python files[2] * Spaces instead of tabs in the Javascript sources * English language (code, variables, comments, ...) * Comments where necessary: Tell *why* the code does something like it does it, structure your code * Following the general architecture - - If your PR needs to make changes to the Stylesheets, change the ``.less`` files - from which the CSS is compiled. -5. **Test your changes thoroughly**. That also means testing with usage + * If your PR needs to make changes to the Stylesheets, change the + ``.less`` files from which the CSS is compiled. + * Make sure you do not add dead code (e.g. commented out left-overs + from experiments). +6. Ensure your changes **pass the existing unit tests**. PRs that break + those cannot be accepted. +7. **Test your changes thoroughly**. That also means testing with usage scenarios you don't normally use, e.g. if you only use access control, test without and vice versa. If you only test with your printer, test with the virtual printer and vice versa. State in your pull request how your tested your changes. Ideally **add unit tests** - OctoPrint severly lacks in that department, but we are trying to change that, so any new code already covered with a test suite helps a lot! -6. In your pull request's description, **state what your pull request does**, +8. In your pull request's description, **state what your pull request does**, as in, what feature does it implement, what bug does it fix. The more thoroughly you explain your intent behind the PR here, the higher the - chances it will get merged fast. -7. Important: Don't forget to **add yourself to the [AUTHORS](./AUTHORS.md) + chances it will get merged fast. There is a template provided below + that can help you here. +9. Don't forget to **add yourself to the [AUTHORS](./AUTHORS.md) file** :) +Template to use for Pull Request descriptions: + +``` +#### What does this PR do and why is it necessary? + +#### How was it tested? How can it be tested by the reviewer? + +#### Any background context you want to provide? + +#### What are the relevant tickets if any? + +#### Screenshots (if appropriate) + +#### Further notes +``` + ## What do the branches mean? There are three main branches in OctoPrint: @@ -342,6 +366,7 @@ the local version identifier to allow for an exact determination of the active c * 2016-02-10: Added information about branch structure and versioning. * 2016-02-16: Added requirement to add information from template to existing tickets as well, explained issue with "me too" red herrings. + * 2016-03-14: Some more requirements for PRs, and a PR template. ## Footnotes * [1] - If you are wondering why, the problem is that anything that you add