101 lines
8.6 KiB
HTML
101 lines
8.6 KiB
HTML
|
<?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"><<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>></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 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.</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, you’re welcome to propose inclusion into upstream.</p><p>There are though some requirements to ensure your changes don’t 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 cdist — at — l.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>
|