| 1 |
Hacking |
| 2 |
======= |
| 3 |
|
| 4 |
Welcome |
| 5 |
------- |
| 6 |
Welcome dear hacker! I invite you to a tour of pointers to |
| 7 |
get into the usable configuration management system, cdist. |
| 8 |
|
| 9 |
The first thing to know is probably that cdist is brought to |
| 10 |
you by people who care about how code looks like and who think |
| 11 |
twice before merging or implementing a feature: Less features |
| 12 |
with good usability are far better than the opposite. |
| 13 |
|
| 14 |
|
| 15 |
Reporting bugs |
| 16 |
-------------- |
| 17 |
If you believe you've found a bug and verified that it is |
| 18 |
in the latest version, drop a mail to the cdist mailing list, |
| 19 |
subject prefixed with "[BUG] " or create an issue on code.ungleich.ch. |
| 20 |
|
| 21 |
|
| 22 |
Coding conventions (everywhere) |
| 23 |
------------------------------- |
| 24 |
If something should be improved or needs to be fixed, add the word FIXME |
| 25 |
nearby, so grepping for FIXME gives all positions that need to be fixed. |
| 26 |
|
| 27 |
Indentation is 4 spaces (welcome to the python world). |
| 28 |
|
| 29 |
|
| 30 |
How to submit stuff for inclusion into upstream cdist |
| 31 |
----------------------------------------------------- |
| 32 |
If you did some cool changes to cdist, which you think might be of benefit to other |
| 33 |
cdist users, you're welcome to propose inclusion into upstream. |
| 34 |
|
| 35 |
There are some requirements to ensure your changes don't break other peoples |
| 36 |
work nor kill the authors brain: |
| 37 |
|
| 38 |
- All files should contain the usual header (Author, Copying, etc.) |
| 39 |
- Code submission must be done via git |
| 40 |
- Do not add cdist/conf/manifest/init - This file should only be touched in your |
| 41 |
private branch! |
| 42 |
- Code to be included should be branched of the upstream "master" branch |
| 43 |
|
| 44 |
- Exception: Bugfixes to a version branch |
| 45 |
|
| 46 |
- On a merge request, always name the branch I should pull from |
| 47 |
- Always ensure **all** manpages build. Use **./build man** to test. |
| 48 |
- If you developed more than **one** feature, consider submitting them in |
| 49 |
separate branches. This way one feature can already be included, even if |
| 50 |
the other needs to be improved. |
| 51 |
|
| 52 |
As soon as your work meets these requirements, write a mail |
| 53 |
for inclusion to the mailinglist **cdist-configuration-management at googlegroups.com** |
| 54 |
or open a merge request at https://code.ungleich.ch/ungleich-public/cdist. |
| 55 |
|
| 56 |
|
| 57 |
How to submit a new type |
| 58 |
------------------------ |
| 59 |
For detailed information about types, see `cdist type <cdist-type.html>`_. |
| 60 |
|
| 61 |
Submitting a type works as described above, with the additional requirement |
| 62 |
that a corresponding manpage named man.rst in ReSTructured text format with |
| 63 |
the manpage-name "cdist-type__NAME" is included in the type directory |
| 64 |
AND the manpage builds (`make man`). |
| 65 |
|
| 66 |
Warning: Submitting "exec" or "run" types that simply echo their parameter in |
| 67 |
**gencode** will not be accepted, because they are of no use. Every type can output |
| 68 |
code and thus such a type introduces redundant functionality that is given by |
| 69 |
core cdist already. |
| 70 |
|
| 71 |
|
| 72 |
Example git workflow |
| 73 |
--------------------- |
| 74 |
The following workflow works fine for most developers |
| 75 |
|
| 76 |
.. code-block:: sh |
| 77 |
|
| 78 |
# get latest upstream master branch |
| 79 |
git clone https://code.ungleich.ch/ungleich-public/cdist.git |
| 80 |
|
| 81 |
# update if already existing |
| 82 |
cd cdist; git fetch -v; git merge origin/master |
| 83 |
|
| 84 |
# create a new branch for your feature/bugfix |
| 85 |
cd cdist # if you haven't done before |
| 86 |
git checkout -b documentation_cleanup |
| 87 |
|
| 88 |
# *hack* |
| 89 |
*hack* |
| 90 |
|
| 91 |
# clone the cdist repository on code.ungleich.ch if you haven't done so |
| 92 |
|
| 93 |
# configure your repo to know about your clone (only once) |
| 94 |
git remote add ungleich [email protected]:YOURUSERNAME/cdist.git |
| 95 |
|
| 96 |
# push the new branch to ungleich gitlab |
| 97 |
git push ungleich documentation_cleanup |
| 98 |
|
| 99 |
# (or everything) |
| 100 |
git push --mirror ungleich |
| 101 |
|
| 102 |
# create a merge request at ungleich gitlab (use a browser) |
| 103 |
# *fixthingsbecausequalityassurancefoundissuesinourpatch* |
| 104 |
*hack* |
| 105 |
|
| 106 |
# push code to ungleich gitlab again |
| 107 |
git push ... # like above |
| 108 |
|
| 109 |
# add comment that everything should be green now (use a browser) |
| 110 |
|
| 111 |
# go back to master branch |
| 112 |
git checkout master |
| 113 |
|
| 114 |
# update master branch that includes your changes now |
| 115 |
git fetch -v origin |
| 116 |
git diff master..origin/master |
| 117 |
git merge origin/master |
| 118 |
|
| 119 |
If at any point you want to go back to the original master branch, you can |
| 120 |
use **git stash** to stash your changes away:: |
| 121 |
|
| 122 |
.. code-block:: sh |
| 123 |
|
| 124 |
# assume you are on documentation_cleanup |
| 125 |
git stash |
| 126 |
|
| 127 |
# change to master and update to most recent upstream version |
| 128 |
git checkout master |
| 129 |
git fetch -v origin |
| 130 |
git merge origin/master |
| 131 |
|
| 132 |
Similarly when you want to develop another new feature, you go back |
| 133 |
to the master branch and create another branch based on it:: |
| 134 |
|
| 135 |
.. code-block:: sh |
| 136 |
|
| 137 |
# change to master and update to most recent upstream version |
| 138 |
git checkout master |
| 139 |
git fetch -v origin |
| 140 |
git merge origin/master |
| 141 |
|
| 142 |
git checkout -b another_feature |
| 143 |
|
| 144 |
(you can repeat the code above for as many features as you want to develop |
| 145 |
in parallel) |