summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md89
1 files changed, 89 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..25fa4b6e4
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,89 @@
+# Contributing to Hercules
+
+Hello! Third party patches are essential to keep Hercules great. We want to
+keep it as easy as possible to contribute changes that get things working in
+your environment. There are a few guidelines that we need contributors to
+follow so that we can have a chance of keeping on top of things.
+
+## Hercules Core vs Modules
+
+Due to the nature of the project, and the wide range of different applications
+it has, we provide a plugin interface, to keep the core clean of unnecessary
+features.
+
+Generally, bugfixes and improvements to existing code, as well as the
+implementation of official Ragnarok Online features and content, should be part
+of the Hercules core, while custom functionalities should be moved to plugins,
+to avoid burdening the core with code potentially useful only to a small subset
+of users.
+
+If you are unsure of whether your contribution should be implemented as a
+module or part of Hercules Core, you may visit [#Hercules on Rizon
+IRC](http://herc.ws/board/topic/91-hercules-irc/), create an issue on GitHub,
+or drop us an email at dev@herc.ws
+
+## Getting Started
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Open an issue in GitHub, if one does not already exist.
+ * Clearly describe the issue including steps to reproduce when it is a bug.
+ * Describe your configuration, following the provided template.
+* Fork the repository on GitHub
+
+## Submitting an Issue on GitHub
+
+When you open an issue, in order for it to be helpful, you should include as
+much description as possible of the issue you are observing or feature you're
+suggesting.
+
+If you're reporting an issue, you should describe your setup, and provide the
+output of `./map-server --version`.
+
+If you report a crash, make sure that you include a backtrace of the crash,
+generated with either gdb or Visual Studio (depending on your build
+environment). For the backtrace to be useful, you need to compile Hercules in
+debug mode.
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+ * This is usually the master branch.
+ * To quickly create a topic branch based on master; `git checkout -b
+ my_contribution master`. Please avoid working directly on the
+ `master` branch.
+* Make commits of logical units. Each commit you submit, must be atomic and
+ complete. **Each commit must do one thing, and do it well.** For separate
+ fixes, make separate commits. Even if this causes commits that only affect
+ one line of code.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure you follow our [coding style guidelines](http://TODO).
+* Make sure your commit messages are complete, describe the changes you made,
+ and in proper English language. Make sure you mention the ID of the issue
+ you fix.
+* Make sure your changes don't accidentally break anything when, for example,
+ Hercules is compiled with different settings.
+
+### Making Trivial Changes
+
+For changes of a trivial nature to comments and documentation, it is not always
+necessary to create a new issue in GitHub.
+
+## Submitting Changes
+
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository in the HerculesWS organization.
+* The dev team looks at Pull Requests on a weekly basis, compatibly with the
+ amount of patches in review queue and current workload.
+* After feedback has been given we expect responses within two weeks. After two
+ weeks we may close the pull request if it isn't showing any activity.
+
+## Other ways to help
+
+* You can help us diagnose and fix existing bugs by asking and providing answers for the following:
+
+ * Is the bug reproducible as explained?
+ * Is it reproducible in other environments?
+ * Are the steps to reproduce the bug clear? If not, can you describe how you might reproduce it?
+ * Is this bug something you have run into? Would you appreciate it being looked into faster?
+
+* You can close fixed bugs by testing old bugs to see if they are still happening.