Debian Codegraph @

docs/src/cdist-hacker.rst

raw
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)