cdist/docs/man/man7/cdist-hacker.text

cdist-hacker(7)
===============
Nico Schottelius <nico-cdist--@--schottelius.org>


NAME
----
cdist-hacker - How to get (stuff) into cdist


WELCOME
-------
Welcome dear hacker! I invite you to a tour of pointers to
get into the usable configuration mangament system, cdist.

The first thing to know is probably that cdist is brought to
you by people who care about how code looks like and who think
twice before merging or implementing a feature: Less features
with good usability are far better than the opposite.


REPORTING BUGS
--------------
If you believe you've found a bug and verified that it is
in the latest version, drop a mail to the cdist mailing list,
subject prefixed with "[BUG] " or create an issue on github.


CODING CONVENTIONS (EVERYWHERE)
-------------------------------
If something should be better done or needs to fixed, add the word FIXME
nearby, so grepping for FIXME gives all positions that need to be fixed.

Indention is 4 spaces (welcome to the python world).


HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST
-----------------------------------------------------
If you did some cool changes to cdist, which you value as a benefit for
everybody using cdist, you're welcome to propose inclusion into upstream.

There are though some requirements to ensure your changes don't break others
work nor kill the authors brain:

- All files should contain the usual header (Author, Copying, etc.)
- Code submission must be done via git
- Do not add cdist/conf/manifest/init - This file should only be touched in your
  private branch!
- Code to be included should be branched of the upstream "master" branch
   - Exception: Bugfixes to a version branch
- On a merge request, always name the branch I should pull from
- Always ensure **all** manpages build. Use **./build man** to test.
- If you developed more than **one** feature, consider submitting them in
  separate branches. This way one feature can already be included, even if
  the other needs to be improved.

As soon as your work meets these requirements, write a mail
for inclusion to the mailinglist **cdist at cdist -- at -- l.schottelius.org**
or open a pull request at http://github.com/telmich/cdist.


HOW TO SUBMIT A NEW TYPE
------------------------
For detailled information about types, see cdist-type(7).

Submitting a type works as described above, with the additional requirement
that a corresponding manpage named man.text in asciidoc format with
the manpage-name "cdist-type__NAME" is included in the type directory
AND asciidoc is able to compile it (i.e. do NOT have to many "=" in the second
line).

Warning: Submitting "exec" or "run" types that simply echo their parameter in
gencode* will not be accepted, because they are of no use. Every type can output
code and thus such a type introduces redundant functionality that is given by
core cdist already.




SEE ALSO
--------
- cdist(7)


COPYING
-------
Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is
granted under the terms of the GNU General Public License version 3 (GPLv3).