Refreshed contributing docs

netbox-community · Nov 3, 2017 · 4801343 · 4801343
1 parent 74cc8c0
commit 4801343
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 78 deletions.
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -4,8 +4,9 @@
     remove the "is:open" filter from the search bar to include closed issues.
 
     Check the appropriate type for your issue below by placing an x between the
-    brackets. If none of the below apply, please raise your issue for
-    discussion on our mailing list:
+    brackets. For assistance with installation issues, or for any other issues
+    other than those listed below, please raise your topic for discussion on
+    our mailing list:
 
         https://groups.google.com/forum/#!forum/netbox-discuss
 
@@ -20,22 +21,30 @@
 <!--
     Please describe the environment in which you are running NetBox. (Be sure
     to verify that you are running the latest stable release of NetBox before
-    submitting a bug report.)
+    submitting a bug report.) If you are submitting a bug report and have made
+    any changes to the code base, please first validate that your bug can be
+    recreated while running an official release.
 -->
 ### Environment
 * Python version:  <!-- Example: 3.5.4 -->
 * NetBox version:  <!-- Example: 2.1.3 -->
 
 <!--
     BUG REPORTS must include:
-        * A list of the steps needed to reproduce the bug
-        * A description of the expected behavior
+        * A list of the steps needed for someone else to reproduce the bug
+        * A description of the expected and observed behavior
         * Any relevant error messages (screenshots may also help)
 
     FEATURE REQUESTS must include:
         * A detailed description of the proposed functionality
         * A use case for the new feature
         * A rough description of any necessary changes to the database schema
         * Any relevant third-party libraries which would be needed
+
+    Do not prepend any sort of tag to your issue's title. An administator will
+    review your issue and assign labels as appropriate.
+
+    Please note that, due to an excessive backlog of feature requests, we are
+    not currently accepting any proposals which extend NetBox's feature scope.
 -->
 ### Description
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,8 +1,8 @@
 ## Getting Help
 
 If you encounter any issues installing or using NetBox, try one of the
-following resources to get assistance. Please **do not** open a GitHub
-issue except to report bugs or request features.
+following resources to get assistance. Please **do not** open a GitHub issue
+except to report bugs or request features.
 
 ### Mailing List
 
@@ -13,107 +13,97 @@ installation. You can find us [here](https://groups.google.com/forum/#!forum/net
 ### Freenode IRC
 
 For real-time discussion, you can join the #netbox channel on [Freenode](https://freenode.net/).
-You can connect to Freenode at irc.freenode.net using an IRC client, or
-you can use their [webchat client](https://webchat.freenode.net/).
+You can connect to Freenode at irc.freenode.net using an IRC client, or you can
+use their [webchat client](https://webchat.freenode.net/).
 
 ## Reporting Bugs
 
 * First, ensure that you've installed the [latest stable version](https://github.com/digitalocean/netbox/releases) of
-NetBox. If you're running an older version, it's possible that the bug
-has already been fixed.
-
-* Next, check the GitHub [issues list](https://github.com/digitalocean/netbox/issues) to see if the bug you've found has
-already been reported. If you think you may be experiencing a reported
-issue that hasn't already been resolved, please click "add a reaction"
-in the top right corner of the issue and add a thumbs up (+1). You might
-also want to add a comment describing how it's affecting your
-installation. This will allow us to prioritize bugs based on how many
-users are affected.
-
-* If you haven't found an existing issue that describes your suspected
-bug, please inquire about it on the mailing list. **Do not** file an
-issue until you have received confirmation that it is in fact a bug.
-Invalid issues are very distracting and slow the pace at which NetBox is
-developed.
-
-* When submitting an issue, please be as descriptive as possible. Be
-sure to include:
+NetBox. If you're running an older version, it's possible that the bug has
+already been fixed.
+
+* Next, check the GitHub [issues list](https://github.com/digitalocean/netbox/issues) to see if the bug you've found has already
+been reported. If you think you may be experiencing a reported issue that
+hasn't already been resolved, please click "add a reaction" in the top right
+corner of the issue and add a thumbs up (+1). You mightalso want to add a
+comment describing how it's affecting your installation. This will allow us to
+prioritize bugs based on how many users are affected.
+
+* If you haven't found an existing issue that describes your suspected bug,
+please inquire about it on the mailing list. **Do not** file an issue until you
+have received confirmation that it is in fact a bug. Invalid issues are very
+distracting and slow the pace at which NetBox is developed.
+
+* When submitting an issue, please be as descriptive as possible. Be sure to
+include:
 
     * The environment in which NetBox is running
-    * The exact steps that can be taken to reproduce the issue (if
-      applicable)
+    * The exact steps that can be taken to reproduce the issue (if applicable)
     * Any error messages generated
     * Screenshots (if applicable)
 
 * Please avoid prepending any sort of tag (e.g. "[Bug]") to the issue title.
 The issue will be reviewed by a moderator after submission and the appropriate
 labels will be applied.
 
-* Keep in mind that we prioritize bugs based on their severity and how
-much work is required to resolve them. It may take some time for someone
-to address your issue.
+* Keep in mind that we prioritize bugs based on their severity and how much
+work is required to resolve them. It may take some time for someone to address
+your issue.
 
 ## Feature Requests
 
-* First, check the GitHub [issues list](https://github.com/digitalocean/netbox/issues) to see if the feature you're
-requesting is already listed. (Be sure to search closed issues as well,
-since some feature requests are rejected.) If the feature you'd like to
-see has already been requested, click "add a reaction" in the top right
-corner of the issue and add a thumbs up (+1). This ensures that the
-issue has a better chance of making it onto the roadmap. Also feel free
-to add a comment with any additional justification for the feature.
-(However, note that comments with no substance other than a "+1" will be
-deleted. Please use GitHub's reactions feature to indicate your
-support.)
-
-* While suggestions for new features are welcome, it's important to
-limit the scope of NetBox's feature set to avoid feature creep. For
-example, the following features would be firmly out of scope for NetBox:
-
-    * Ticket management
-    * Network state monitoring
-    * Acting as a DNS server
-    * Acting as an authentication server
+* First, check the GitHub [issues list](https://github.com/digitalocean/netbox/issues) to see if the feature you're requesting
+is already listed. (Be sure to search closed issues as well, since some
+feature requests have been rejected.) If the feature you'd like to see has
+already been requested and is open, click "add a reaction" in the top right
+corner of the issue and add a thumbs up (+1). This ensures that the issue has
+a better chance of receiving attention. Also feel free to add a comment with
+any additional justification for the feature. (However, note that comments with
+no substance other than a "+1" will be deleted. Please use GitHub's reactions
+feature to indicate your support.)
+
+* Due to an excessive backlog of feature requests, we are not currently
+accepting any proposals which substantially extend NetBox's functionality
+beyond its current feature set. This includes the introduction of any new views
+or models which have not already been proposed in an existing feature request.
 
 * Before filing a new feature request, consider raising your idea on the
-mailing list first. Feedback you receive there will help validate and
-shape the proposed feature before filing a formal issue.
+mailing list first. Feedback you receive there will help validate and shape the
+proposed feature before filing a formal issue.
 
-* Good feature requests are very narrowly defined. Be sure to enumerate
-specific functionality and data schema. The more effort you put into
-writing a feature request, the better its chance is of being
+* Good feature requests are very narrowly defined. Be sure to thoroughly
+describe the functionality and data model(s) being proposed. The more effort
+you put into writing a feature request, the better its chance is of being
 implemented. Overly broad feature requests will be closed.
 
 * When submitting a feature request on GitHub, be sure to include the
 following:
 
     * A detailed description of the proposed functionality
-    * A use case for the feature; who would use it and what value it
-      would add to NetBox
-    * A rough description of changes necessary to the database schema
-      (if applicable)
-    * Any third-party libraries or other resources which would be
-      involved
-
-* Please avoid prepending any sort of tag (e.g. "[Feature]") to the issue title.
-The issue will be reviewed by a moderator after submission and the appropriate
-labels will be applied.
+    * A use case for the feature; who would use it and what value it would add
+      to NetBox
+    * A rough description of changes necessary to the database schema (if
+      applicable)
+    * Any third-party libraries or other resources which would be involved
+
+* Please avoid prepending any sort of tag (e.g. "[Feature]") to the issue
+title. The issue will be reviewed by a moderator after submission and the
+appropriate labels will be applied.
 
 ## Submitting Pull Requests
 
-* Be sure to open an issue before starting work on a pull request, and
-discuss your idea with the NetBox maintainers before beginning work.
-This will help prevent wasting time on something that might we might not
-be able to implement. When suggesting a new feature, also make sure it
-won't conflict with any work that's already in progress.
+* Be sure to open an issue before starting work on a pull request, and discuss
+your idea with the NetBox maintainers before beginning work. This will help
+prevent wasting time on something that might we might not be able to implement.
+When suggesting a new feature, also make sure it won't conflict with any work
+that's already in progress.
 
-* When submitting a pull request, please be sure to work off of the
-`develop` branch, rather than `master`. In NetBox, the `develop` branch
-is used for ongoing development, while `master` is used for tagging new
-stable releases.
+* When submitting a pull request, please be sure to work off of the `develop`
+branch, rather than `master`. The `develop` branch is used for ongoing
+development, while `master` is used for tagging new stable releases.
 
-* All code submissions should meet the following criteria (CI will
-enforce these checks):
+* All code submissions should meet the following criteria (CI will enforce
+these checks):
 
     * Python syntax is valid
     * All tests pass when run with `./manage.py test`