dfhack/Contributing.rst

######################
Contributing to DFHACK
######################

.. contents::

Contributing to DFHack
======================

Several things should be kept in mind when contributing to DFHack.

-----------
Code Format
-----------

* Four space indents for C++. Never use tabs for indentation in any language.
* LF (Unix style) line terminators
* Avoid trailing whitespace
* UTF-8 encoding
* For C++:

  * Opening and closing braces on their own lines or opening brace at the end of the previous line
  * Braces placed at original indent level if on their own lines
  * #includes should be sorted. C++ libraries first, then dfhack modules, then df structures, then local includes. Within each category they should be sorted alphabetically. This policy is currently broken by most C++ files but try to follow it if you can.

-------------------------------
How to get new code into DFHack
-------------------------------

* Submit pull requests to the develop branch, not the master branch. The master branch always points at the most recent release.
* Use new branches for each feature/fix so that your changes can be merged independently.
* If possible, compile on multiple platforms
* Do update NEWS/Contributors.rst
* Do **NOT** run fix-texts.sh or update .html files (except to locally test changes to .rst files) 
* Create a Github Pull Request once finished
* Work done against `issues <http://github.com/DFHack/dfhack/issues>`_ that are tagged "bug report" gets priority

  * Submit ideas and bug reports as issues on github. Posts in the forum thread are also acceptable but can get missed or forgotten more easily.

---------------
Memory research
---------------
If you want to do memory research, you'll need some tools and some knowledge.
In general, you'll need a good memory viewer and optionally something
to look at machine code without getting crazy :)

Good windows tools include:

* Cheat Engine
* IDA Pro 5.0 (freely available for non-commercial use)

Good linux tools:

* angavrilov's df-structures gui (visit us on IRC for details).
* edb (Evan's Debugger)
* IDA Pro 5.0 running under Wine
* Some of the tools residing in the ``legacy`` dfhack branch.

Using publicly known information and analyzing the game's data is preferred.
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00			`######################`
			`Contributing to DFHACK`
			`######################`

			`.. contents::`

			`Contributing to DFHack`
			`======================`

			`Several things should be kept in mind when contributing to DFHack.`

Rename and update Contributing.rst 2015-01-27 13:12:46 -07:00			`-----------`
			`Code Format`
			`-----------`
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00
No tabs! 2015-01-31 20:50:37 -07:00			`* Four space indents for C++. Never use tabs for indentation in any language.`
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00			`* LF (Unix style) line terminators`
Tweak contributing.rst. 2015-01-31 19:38:42 -07:00			`* Avoid trailing whitespace`
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00			`* UTF-8 encoding`
Rename and update Contributing.rst 2015-01-27 13:12:46 -07:00			`* For C++:`

Tweak contributing.rst. 2015-01-31 19:38:42 -07:00			`* Opening and closing braces on their own lines or opening brace at the end of the previous line`
Contributing tweaks. 2015-01-31 21:04:35 -07:00			`* Braces placed at original indent level if on their own lines`
Contributing typo. 2015-01-31 21:06:23 -07:00			`* #includes should be sorted. C++ libraries first, then dfhack modules, then df structures, then local includes. Within each category they should be sorted alphabetically. This policy is currently broken by most C++ files but try to follow it if you can.`
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00
			`-------------------------------`
			`How to get new code into DFHack`
			`-------------------------------`

Tweak contributing.rst. 2015-01-31 19:38:42 -07:00			`* Submit pull requests to the develop branch, not the master branch. The master branch always points at the most recent release.`
			`* Use new branches for each feature/fix so that your changes can be merged independently.`
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00			`* If possible, compile on multiple platforms`
			`* Do update NEWS/Contributors.rst`
Tweak contributing.rst. 2015-01-31 19:38:42 -07:00			`* Do NOT run fix-texts.sh or update .html files (except to locally test changes to .rst files)`
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00			`* Create a Github Pull Request once finished`
			* Work done against `issues <http://github.com/DFHack/dfhack/issues>`_ that are tagged "bug report" gets priority

Tweak contributing.rst. 2015-01-31 19:38:42 -07:00			`* Submit ideas and bug reports as issues on github. Posts in the forum thread are also acceptable but can get missed or forgotten more easily.`
Initial Contribute.rst Hope to flesh out the code format section more 2015-01-22 21:05:46 -07:00
			`---------------`
			`Memory research`
			`---------------`
			`If you want to do memory research, you'll need some tools and some knowledge.`
			`In general, you'll need a good memory viewer and optionally something`
			`to look at machine code without getting crazy :)`

			`Good windows tools include:`

			`* Cheat Engine`
			`* IDA Pro 5.0 (freely available for non-commercial use)`

			`Good linux tools:`

			`* angavrilov's df-structures gui (visit us on IRC for details).`
			`* edb (Evan's Debugger)`
			`* IDA Pro 5.0 running under Wine`
			* Some of the tools residing in the ``legacy`` dfhack branch.

Tweak contributing.rst. 2015-01-31 19:38:42 -07:00			`Using publicly known information and analyzing the game's data is preferred.`