2016-06-17 19:28:16 +00:00
|
|
|
Hacking
|
|
|
|
=======
|
2016-06-23 14:08:59 +00:00
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
Welcome
|
2011-03-24 14:26:06 +00:00
|
|
|
-------
|
|
|
|
Welcome dear hacker! I invite you to a tour of pointers to
|
2017-06-30 15:01:07 +00:00
|
|
|
get into the usable configuration management system, cdist.
|
2011-03-24 14:26:06 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
Reporting bugs
|
2011-04-06 20:13:30 +00:00
|
|
|
--------------
|
|
|
|
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,
|
2018-12-30 10:59:34 +00:00
|
|
|
subject prefixed with "[BUG] " or create an issue on code.ungleich.ch.
|
2011-04-06 20:13:30 +00:00
|
|
|
|
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
Coding conventions (everywhere)
|
2011-04-06 18:21:36 +00:00
|
|
|
-------------------------------
|
2017-06-30 15:01:07 +00:00
|
|
|
If something should be improved or needs to be fixed, add the word FIXME
|
2011-04-06 18:21:36 +00:00
|
|
|
nearby, so grepping for FIXME gives all positions that need to be fixed.
|
|
|
|
|
2017-06-30 15:01:07 +00:00
|
|
|
Indentation is 4 spaces (welcome to the python world).
|
2012-01-17 22:53:58 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
How to submit stuff for inclusion into upstream cdist
|
2011-03-24 14:26:06 +00:00
|
|
|
-----------------------------------------------------
|
2017-06-30 15:01:07 +00:00
|
|
|
If you did some cool changes to cdist, which you think might be of benefit to other
|
|
|
|
cdist users, you're welcome to propose inclusion into upstream.
|
2011-03-24 14:26:06 +00:00
|
|
|
|
2017-06-30 15:01:07 +00:00
|
|
|
There are some requirements to ensure your changes don't break other peoples
|
2011-03-24 14:26:06 +00:00
|
|
|
work nor kill the authors brain:
|
|
|
|
|
2011-06-02 06:14:50 +00:00
|
|
|
- All files should contain the usual header (Author, Copying, etc.)
|
2011-03-24 14:26:06 +00:00
|
|
|
- Code submission must be done via git
|
2012-12-09 22:41:50 +00:00
|
|
|
- Do not add cdist/conf/manifest/init - This file should only be touched in your
|
2011-03-24 14:58:47 +00:00
|
|
|
private branch!
|
2011-04-18 06:35:52 +00:00
|
|
|
- Code to be included should be branched of the upstream "master" branch
|
2016-05-20 06:50:56 +00:00
|
|
|
|
2011-04-18 06:35:52 +00:00
|
|
|
- Exception: Bugfixes to a version branch
|
2016-05-20 06:50:56 +00:00
|
|
|
|
2011-10-04 14:43:13 +00:00
|
|
|
- On a merge request, always name the branch I should pull from
|
2012-01-17 22:53:58 +00:00
|
|
|
- Always ensure **all** manpages build. Use **./build man** to test.
|
2011-04-18 06:35:52 +00:00
|
|
|
- If you developed more than **one** feature, consider submitting them in
|
2013-06-03 16:11:19 +00:00
|
|
|
separate branches. This way one feature can already be included, even if
|
2011-04-18 06:35:52 +00:00
|
|
|
the other needs to be improved.
|
2011-03-24 14:26:06 +00:00
|
|
|
|
2012-03-09 22:39:47 +00:00
|
|
|
As soon as your work meets these requirements, write a mail
|
2016-10-12 18:15:07 +00:00
|
|
|
for inclusion to the mailinglist **cdist-configuration-management at googlegroups.com**
|
2018-12-30 10:59:34 +00:00
|
|
|
or open a merge request at https://code.ungleich.ch/ungleich-public/cdist.
|
2011-03-24 14:26:06 +00:00
|
|
|
|
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
How to submit a new type
|
2011-03-24 14:26:06 +00:00
|
|
|
------------------------
|
2016-08-22 07:24:48 +00:00
|
|
|
For detailed information about types, see `cdist type <cdist-type.html>`_.
|
2012-02-13 07:49:49 +00:00
|
|
|
|
2011-03-24 14:26:06 +00:00
|
|
|
Submitting a type works as described above, with the additional requirement
|
2018-10-31 19:24:07 +00:00
|
|
|
that a corresponding manpage named man.rst in ReSTructured text format with
|
2011-03-24 14:26:06 +00:00
|
|
|
the manpage-name "cdist-type__NAME" is included in the type directory
|
2018-10-31 19:24:07 +00:00
|
|
|
AND the manpage builds (`make man`).
|
2011-03-24 14:26:06 +00:00
|
|
|
|
2012-02-13 07:49:49 +00:00
|
|
|
Warning: Submitting "exec" or "run" types that simply echo their parameter in
|
2016-05-20 06:50:56 +00:00
|
|
|
**gencode** will not be accepted, because they are of no use. Every type can output
|
2012-02-13 07:49:49 +00:00
|
|
|
code and thus such a type introduces redundant functionality that is given by
|
|
|
|
core cdist already.
|
|
|
|
|
2011-03-24 14:26:06 +00:00
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
Example git workflow
|
2013-12-04 20:22:18 +00:00
|
|
|
---------------------
|
2016-06-17 19:28:16 +00:00
|
|
|
The following workflow works fine for most developers
|
|
|
|
|
|
|
|
.. code-block:: sh
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# get latest upstream master branch
|
2018-12-30 10:59:34 +00:00
|
|
|
git clone https://code.ungleich.ch/ungleich-public/cdist.git
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# update if already existing
|
|
|
|
cd cdist; git fetch -v; git merge origin/master
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# create a new branch for your feature/bugfix
|
|
|
|
cd cdist # if you haven't done before
|
|
|
|
git checkout -b documentation_cleanup
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# *hack*
|
|
|
|
*hack*
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2018-12-30 10:59:34 +00:00
|
|
|
# clone the cdist repository on code.ungleich.ch if you haven't done so
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# configure your repo to know about your clone (only once)
|
2018-12-30 10:59:34 +00:00
|
|
|
git remote add ungleich git@code.ungleich.ch:YOURUSERNAME/cdist.git
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2018-12-30 10:59:34 +00:00
|
|
|
# push the new branch to ungleich gitlab
|
|
|
|
git push ungleich documentation_cleanup
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# (or everything)
|
2018-12-30 10:59:34 +00:00
|
|
|
git push --mirror ungleich
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2018-12-30 10:59:34 +00:00
|
|
|
# create a merge request at ungleich gitlab (use a browser)
|
2016-05-20 06:50:56 +00:00
|
|
|
# *fixthingsbecausequalityassurancefoundissuesinourpatch*
|
|
|
|
*hack*
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2018-12-30 10:59:34 +00:00
|
|
|
# push code to ungleich gitlab again
|
2016-05-20 06:50:56 +00:00
|
|
|
git push ... # like above
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# add comment that everything should be green now (use a browser)
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# go back to master branch
|
|
|
|
git checkout master
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# update master branch that includes your changes now
|
|
|
|
git fetch -v origin
|
|
|
|
git diff master..origin/master
|
|
|
|
git merge origin/master
|
2013-12-04 20:22:18 +00:00
|
|
|
|
|
|
|
If at any point you want to go back to the original master branch, you can
|
2016-05-20 06:50:56 +00:00
|
|
|
use **git stash** to stash your changes away::
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
.. code-block:: sh
|
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# assume you are on documentation_cleanup
|
|
|
|
git stash
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# change to master and update to most recent upstream version
|
|
|
|
git checkout master
|
|
|
|
git fetch -v origin
|
|
|
|
git merge origin/master
|
2013-12-04 20:22:18 +00:00
|
|
|
|
2017-06-30 15:01:07 +00:00
|
|
|
Similarly when you want to develop another new feature, you go back
|
2016-05-20 06:50:56 +00:00
|
|
|
to the master branch and create another branch based on it::
|
2013-12-04 20:25:10 +00:00
|
|
|
|
2016-06-17 19:28:16 +00:00
|
|
|
.. code-block:: sh
|
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
# change to master and update to most recent upstream version
|
|
|
|
git checkout master
|
|
|
|
git fetch -v origin
|
|
|
|
git merge origin/master
|
2013-12-04 20:25:10 +00:00
|
|
|
|
2016-05-20 06:50:56 +00:00
|
|
|
git checkout -b another_feature
|
2013-12-04 20:25:10 +00:00
|
|
|
|
|
|
|
(you can repeat the code above for as many features as you want to develop
|
|
|
|
in parallel)
|