summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md164
1 files changed, 164 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..84f3842
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,164 @@
+# Contributing
+
+Thank you for considering contributing your time and effort to this Nagios project.
+This document serves as our guidelines for contribution. Keep in mind that these
+are simply *guidelines* - nothing here is set in stone.
+
+## Questions
+
+If you have a question, you don't need to file an Issue. You can simply connect
+with the Nagios Support Team via the
+[Nagios Support Forum](https://support.nagios.com/forum/).
+
+Not to say that you **can't** open an Issue - but you'll likely get a much faster
+response by posting it on the forum.
+
+## Ideas
+
+If you have an idea your best bet is to open an Issue. This gets it on the radar much
+quicker than any other method.
+
+First, let's define what an "Idea" really is. An Idea is simply an
+[Enhancement](#enhancements) request in its infancy.
+There's really nothing to it!
+
+Something as simple as "I think that this project should somehow connect with a
+widget" is a valid Idea.
+
+These are unrefined and raw. That's why you open an issue - so everyone gets a chance
+to chime in and come up with a plan!
+
+## Feedback
+
+Feedback can be given via several methods. The *easiest* method is by opening an Issue.
+You're more than welcome to leave feedback on the
+[Nagios Support Forum](https://support.nagios.com/forum/) as well.
+
+By opening an Issue, however, you're insuring that the maintainers and reviewers are
+the first ones to see the feedback. In most cases, this is likely ideal.
+
+## Bugs
+
+Here's where it starts to get serious.
+
+Following the guidelines outlined in this section allows the maintainers, developers, and
+community to understand and reproduce your bug report.
+
+Make sure to search existing open and closed [Issues](https://guides.github.com/features/issues/)
+before opening a bug report. If you find a closed Issue that seems like it's the same
+thing that you're experiencing, open a new Issue and include a link to the original Issue
+in the body of the new one.
+
+**If you have a bug, you *NEED* to open an Issue.**
+
+Not only that, but when you open the Issue, this is what we ***absolutely require***:
+
+* Use a clear and concise title for the Issue to identify the problem accurately
+
+* Describe the bug with as much detail as you can
+
+* Include the version of the project containing the bug you're reporting
+
+* Include your operating system information (`uname -a`)
+
+* Include a list of third party modules that are installed and/or loaded
+
+* Explain the behavior you expected to see (and why) vs. what actually happened
+
+Once you've got that covered - there's still more to include if you want to
+make a ***killer*** report:
+
+* Describe the ***exact steps*** that reproduce the problem
+
+* Provide **specific** examples to demonstrate those steps
+
+* If your bug is from an older version, make sure test against the latest (and/or the `maint` branch)
+
+* Include any screenshots that can help explain the issue
+
+* Include a file containing `strace` and/or `valgrind` output
+
+* Explain when the problem started happening: was it after an upgrade? or was it always present?
+
+* Define how reliably you can reproduce the bug
+
+* Any other information that you decide is relevant is also welcome
+
+## Enhancements
+
+An enhancement is either a completely new feature or an improvement to existing
+functionality. We consider it to be a bit different than idea - based solely
+on the fact that it's more detailed than an idea would be.
+
+So you've got an idea for an ehancement? Great!
+
+Following the guidelines outlined in this section allows maintainers, developers, and
+the community to understand your enhancement and determine whether or not it's worth
+doing and/or what's involved in carrying it out.
+
+Make sure to search open and closed Issues and Pull Requests to determine if
+someone has either submitted the enhancement. If you feel like your enhancement
+is similar to one found, make sure to link the original in your request.
+
+Enhancements are submitted by opening an Issue.
+
+Unlike an [Idea](#idea), when you decide to submit your enhancement and open
+the Issue, we require at least the following information:
+
+* Use a clear and descriptive title to illustrate the enhancement you're requesting
+
+* Describe the current behavior (if it exists) and what changes you think should be made
+
+* Explain the enhancement in detail - make sure it makes sense and is easily understandable
+
+* Specify why the enhancement would be useful and who it would be useful to
+
+* If there is some other project or program where this enhancement already exists, make sure
+to link to it
+
+Beyond that, there are a few more things you can do to make sure you **really** get your
+point across:
+
+* Create a mockup of the enhancement (if applicable) and attach whatever files you can
+
+* Provide a step-by-step description of the suggested enhancement
+
+* Generate a fully dressed use-case for the enhancement request
+
+* Create a specification for the preferred implementation of the enhancement
+
+* Include a timeline regarding development expectations towards the request
+
+## Submitting Code
+
+Everything else in this document has lead up to this moment - how can ***you*** submit
+code to the **project**.
+
+We allow code submissions via [Pull Requests](https://help.github.com/articles/about-pull-requests/).
+These let you (and us) discuss and review any changes to code in any repository you've made.
+
+How to create and manage Pull Requests is outside of the scope of this document, but make
+sure to check out GitHub's official documentation ([link here](https://help.github.com/))
+to get a handle on it.
+
+While you're forking the repository to create a patch or an enhancement, create a *new
+branch* to make the change - it will be easier to submit a pull request using a new
+branch in your forked repository!
+
+When you submit a Pull Request, make sure you follow the guidelines:
+
+* Make sure you're submitting to the proper branch. Branch `maint` is used for the
+**next** bugfix release. The next enhancement release branch will vary.
+
+* ***NEVER*** submit a Pull Request to `master` branch.
+
+* Keep commit messages as concise as possible.
+* Update the appropriate files in regards to your changes:
+
+ * `CHANGES`
+
+ * `THANKS`
+
+* End all committed files with a newline.
+
+* Test your changes and include the results as a comment. \ No newline at end of file