www.nico.schottelius.org/software/cdist/man/3.0.7/man7/cdist-hacker.html
2014-02-08 00:15:35 +01:00

101 lines
No EOL
8.6 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-hacker(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idm140488571926432"></a>cdist-hacker(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_welcome">2. WELCOME</a></span></dt><dt><span class="section"><a href="#_reporting_bugs">3. REPORTING BUGS</a></span></dt><dt><span class="section"><a href="#_coding_conventions_everywhere">4. CODING CONVENTIONS (EVERYWHERE)</a></span></dt><dt><span class="section"><a href="#_how_to_submit_stuff_for_inclusion_into_upstream_cdist">5. HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST</a></span></dt><dt><span class="section"><a href="#_how_to_submit_a_new_type">6. HOW TO SUBMIT A NEW TYPE</a></span></dt><dt><span class="section"><a href="#_example_git_workflow">7. EXAMPLE GIT WORKFLOW</a></span></dt><dt><span class="section"><a href="#_see_also">8. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">9. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-hacker - How to get (stuff) into cdist</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_welcome"></a>2. WELCOME</h2></div></div></div><p>Welcome dear hacker! I invite you to a tour of pointers to
get into the usable configuration mangament system, cdist.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_reporting_bugs"></a>3. REPORTING BUGS</h2></div></div></div><p>If you believe youve 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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_coding_conventions_everywhere"></a>4. CODING CONVENTIONS (EVERYWHERE)</h2></div></div></div><p>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.</p><p>Indention is 4 spaces (welcome to the python world).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_submit_stuff_for_inclusion_into_upstream_cdist"></a>5. HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST</h2></div></div></div><p>If you did some cool changes to cdist, which you value as a benefit for
everybody using cdist, youre welcome to propose inclusion into upstream.</p><p>There are though some requirements to ensure your changes dont break others
work nor kill the authors brain:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
All files should contain the usual header (Author, Copying, etc.)
</li><li class="listitem">
Code submission must be done via git
</li><li class="listitem">
Do not add cdist/conf/manifest/init - This file should only be touched in your
private branch!
</li><li class="listitem">
Code to be included should be branched of the upstream "master" branch
</li><li class="listitem">
Exception: Bugfixes to a version branch
</li><li class="listitem">
On a merge request, always name the branch I should pull from
</li><li class="listitem">
Always ensure <span class="strong"><strong>all</strong></span> manpages build. Use <span class="strong"><strong>./build man</strong></span> to test.
</li><li class="listitem">
If you developed more than <span class="strong"><strong>one</strong></span> feature, consider submitting them in
separate branches. This way one feature can already be included, even if
the other needs to be improved.
</li></ul></div><p>As soon as your work meets these requirements, write a mail
for inclusion to the mailinglist <span class="strong"><strong>cdist at cdistatl.schottelius.org</strong></span>
or open a pull request at <a class="ulink" href="http://github.com/telmich/cdist" target="_top">http://github.com/telmich/cdist</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_submit_a_new_type"></a>6. HOW TO SUBMIT A NEW TYPE</h2></div></div></div><p>For detailled information about types, see cdist-type(7).</p><p>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).</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_example_git_workflow"></a>7. EXAMPLE GIT WORKFLOW</h2></div></div></div><p>The following workflow works fine for most developers:</p><pre class="screen"># get latest upstream master branch
git clone https://github.com/telmich/cdist.git
# update if already existing
cd cdist; git fetch -v; git merge origin/master
# create a new branch for your feature/bugfix
cd cdist # if you haven't done before
git checkout -b documentation_cleanup
# *hack*
*hack*
# clone the cdist repository on github if you haven't done so
# configure your repo to know about your clone (only once)
git remote add github git@github.com:YOURUSERNAME/cdist.git
# push the new branch to github
git push github documentation_cleanup
# (or everything)
git push --mirror github
# create a pull request at github (use a browser)
# *fixthingsbecausequalityassurancefoundissuesinourpatch*
*hack*
# push code to github again
git push ... # like above
# add comment that everything should be green now (use a browser)
# go back to master branch
git checkout master
# update master branch that includes your changes now
git fetch -v origin
git diff master..origin/master
git merge origin/master</pre><p>If at any point you want to go back to the original master branch, you can
use <span class="strong"><strong>git stash</strong></span> to stash your changes away:</p><pre class="screen"># assume you are on documentation_cleanup
git stash
# change to master and update to most recent upstream version
git checkout master
git fetch -v origin
git merge origin/master</pre><p>Similar when you want to develop another new feature, you go back
to the master branch and create another branch based on it:</p><pre class="screen"># change to master and update to most recent upstream version
git checkout master
git fetch -v origin
git merge origin/master
git checkout -b another_feature</pre><p>(you can repeat the code above for as many features as you want to develop
in parallel)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>8. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist(7)
</li><li class="listitem">
git(1)
</li><li class="listitem">
git-checkout(1)
</li><li class="listitem">
git-stash(1)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>9. COPYING</h2></div></div></div><p>Copyright (C) 2011-2013 Nico Schottelius. Free use of this software is
granted under the terms of the GNU General Public License version 3 (GPLv3).</p></div></div></body></html>