Merge lp:~mvo/snappy/snappy-docs-mdlint into lp:~snappy-dev/snappy/snappy-moved-to-github
- snappy-docs-mdlint
- Merge into snappy-moved-to-github
Proposed by
Michael Vogt
Status: | Merged |
---|---|
Approved by: | John Lenton |
Approved revision: | 467 |
Merged at revision: | 466 |
Proposed branch: | lp:~mvo/snappy/snappy-docs-mdlint |
Merge into: | lp:~snappy-dev/snappy/snappy-moved-to-github |
Diff against target: |
322 lines (+134/-93) 7 files modified
debian/control (+3/-1) docs/hashes.md (+8/-8) docs/meta.md (+61/-61) docs/package-names.md (+1/-1) docs/security.md (+22/-22) mdlint.py (+36/-0) run-checks (+3/-0) |
To merge this branch: | bzr merge lp:~mvo/snappy/snappy-docs-mdlint |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Sergio Schvezov | Approve | ||
Review via email: mp+259490@code.launchpad.net |
Commit message
Add simple markdown lint to ensure the tables are correctly rendered and run as part of "run-checks.sh"
Description of the change
This is mostly a RFC, this branch may be overkill and too simplistic at the same time (how often do you have that!).
When looking at https:/
To post a comment you must log in.
Revision history for this message
Sergio Schvezov (sergiusens) wrote : | # |
Revision history for this message
Sergio Schvezov (sergiusens) : | # |
review:
Approve
Revision history for this message
Michael Vogt (mvo) wrote : | # |
Thanks Sergio, I think this makes sense and I added exit code handling now.
Revision history for this message
Snappy Tarmac (snappydevtarmac) wrote : | # |
There are additional revisions which have not been approved in review. Please seek review and approval of these new revisions.
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file 'debian/control' | |||
2 | --- debian/control 2015-05-08 19:42:00 +0000 | |||
3 | +++ debian/control 2015-05-19 14:28:51 +0000 | |||
4 | @@ -14,7 +14,9 @@ | |||
5 | 14 | golang-gocheck-dev, | 14 | golang-gocheck-dev, |
6 | 15 | golang-goconfigparser-dev, | 15 | golang-goconfigparser-dev, |
7 | 16 | golang-pb-dev, | 16 | golang-pb-dev, |
9 | 17 | golang-yaml.v2-dev | 17 | golang-yaml.v2-dev, |
10 | 18 | python3, | ||
11 | 19 | python3-markdown | ||
12 | 18 | Standards-Version: 3.9.6 | 20 | Standards-Version: 3.9.6 |
13 | 19 | Homepage: https://launchpad.net/snappy | 21 | Homepage: https://launchpad.net/snappy |
14 | 20 | Vcs-Browser: http://bazaar.launchpad.net/~snappy-dev/snappy/trunk/files | 22 | Vcs-Browser: http://bazaar.launchpad.net/~snappy-dev/snappy/trunk/files |
15 | 21 | 23 | ||
16 | === modified file 'docs/hashes.md' | |||
17 | --- docs/hashes.md 2015-03-26 20:35:57 +0000 | |||
18 | +++ docs/hashes.md 2015-05-19 14:28:51 +0000 | |||
19 | @@ -6,17 +6,17 @@ | |||
20 | 6 | ## Format | 6 | ## Format |
21 | 7 | 7 | ||
22 | 8 | The yaml looks like this: | 8 | The yaml looks like this: |
24 | 9 | * archive-sha512: the hexdigest of the data.tar.gz | 9 | * archive-sha512: the hexdigest of the data.tar.gz |
25 | 10 | 10 | ||
26 | 11 | Then a list of files/directories/symlinks in the tar that are | 11 | Then a list of files/directories/symlinks in the tar that are |
27 | 12 | described with: | 12 | described with: |
35 | 13 | * name: the full path in the archive | 13 | * name: the full path in the archive |
36 | 14 | * mode: First char is the type "f" for file, "d" for dir, "l" for | 14 | * mode: First char is the type "f" for file, "d" for dir, "l" for |
37 | 15 | symlink. Then the unix permission bits in the form | 15 | symlink. Then the unix permission bits in the form |
38 | 16 | rwxrwxrwx. | 16 | rwxrwxrwx. |
39 | 17 | E.g. a file with mode 0644 is: "frw-r--r--" | 17 | E.g. a file with mode 0644 is: "frw-r--r--" |
40 | 18 | * size: (applies only to files) | 18 | * size: (applies only to files) |
41 | 19 | * sha512: (applies only to files) the hexdigest of the file content | 19 | * sha512: (applies only to files) the hexdigest of the file content |
42 | 20 | 20 | ||
43 | 21 | ## Owner | 21 | ## Owner |
44 | 22 | 22 | ||
45 | 23 | 23 | ||
46 | === modified file 'docs/meta.md' | |||
47 | --- docs/meta.md 2015-05-13 20:41:52 +0000 | |||
48 | +++ docs/meta.md 2015-05-19 14:28:51 +0000 | |||
49 | @@ -16,70 +16,70 @@ | |||
50 | 16 | This file describes the snap package and is the most important file | 16 | This file describes the snap package and is the most important file |
51 | 17 | for a snap package. The following keys are mandatory: | 17 | for a snap package. The following keys are mandatory: |
52 | 18 | 18 | ||
56 | 19 | * `name`: the name of the snap (only `[a-z0-9][a-z0-9+.-]`) | 19 | * `name`: the name of the snap (only `[a-z0-9][a-z0-9+.-]`) |
57 | 20 | * `version`: the version of the snap (only `[a-zA-Z0-9.+~-]` are allowed) | 20 | * `version`: the version of the snap (only `[a-zA-Z0-9.+~-]` are allowed) |
58 | 21 | * `vendor`: the vendor of the snap | 21 | * `vendor`: the vendor of the snap |
59 | 22 | 22 | ||
60 | 23 | The following keys are optional: | 23 | The following keys are optional: |
61 | 24 | 24 | ||
120 | 25 | * `icon`: a SVG icon for the snap that is displayed in the store | 25 | * `icon`: a SVG icon for the snap that is displayed in the store |
121 | 26 | * `explicit-license-agreement`: set to `Y` if the user needs to accept a | 26 | * `explicit-license-agreement`: set to `Y` if the user needs to accept a |
122 | 27 | special `meta/license.txt` before the snap can be installed | 27 | special `meta/license.txt` before the snap can be installed |
123 | 28 | * `license-version`: a string that, when it changes and | 28 | * `license-version`: a string that, when it changes and |
124 | 29 | `explicit-license-agreement` is `Y`, prompts the user to accept the | 29 | `explicit-license-agreement` is `Y`, prompts the user to accept the |
125 | 30 | license again. | 30 | license again. |
126 | 31 | * `type`: (optional) the type of the snap, can be: | 31 | * `type`: (optional) the type of the snap, can be: |
127 | 32 | * `app` - the default if empty | 32 | * `app` - the default if empty |
128 | 33 | * `oem` - a special snap that OEMs can use to customize snappy for | 33 | * `oem` - a special snap that OEMs can use to customize snappy for |
129 | 34 | their hardware | 34 | their hardware |
130 | 35 | * `framework` - a specialized snap that extends the system that other | 35 | * `framework` - a specialized snap that extends the system that other |
131 | 36 | snaps may use | 36 | snaps may use |
132 | 37 | 37 | ||
133 | 38 | * `architectures`: (optional) a yaml list of supported architectures | 38 | * `architectures`: (optional) a yaml list of supported architectures |
134 | 39 | `["all"]` if empty | 39 | `["all"]` if empty |
135 | 40 | * `frameworks`: a list of the frameworks the snap needs as dependencies | 40 | * `frameworks`: a list of the frameworks the snap needs as dependencies |
136 | 41 | 41 | ||
137 | 42 | * `services`: the servies (daemons) that the snap provides | 42 | * `services`: the servies (daemons) that the snap provides |
138 | 43 | * `name`: (required) name of the service (only `[a-zA-Z0-9+.-]`) | 43 | * `name`: (required) name of the service (only `[a-zA-Z0-9+.-]`) |
139 | 44 | * `description`: (required) description of the service | 44 | * `description`: (required) description of the service |
140 | 45 | * `start`: (required) the command to start the service | 45 | * `start`: (required) the command to start the service |
141 | 46 | * `stop`: (optional) the command to stop the service | 46 | * `stop`: (optional) the command to stop the service |
142 | 47 | * `stop-timeout`: (optional) the time in seconds to wait for the | 47 | * `stop-timeout`: (optional) the time in seconds to wait for the |
143 | 48 | service to stop | 48 | service to stop |
144 | 49 | * `poststop`: a command that runs after the service has stopped | 49 | * `poststop`: a command that runs after the service has stopped |
145 | 50 | * `caps`: (optional) list of additional security policies to add. | 50 | * `caps`: (optional) list of additional security policies to add. |
146 | 51 | See `security.md` for details | 51 | See `security.md` for details |
147 | 52 | * `security-template`: (optional) alternate security template to use | 52 | * `security-template`: (optional) alternate security template to use |
148 | 53 | instead of `default`. See `security.md` for details | 53 | instead of `default`. See `security.md` for details |
149 | 54 | * `security-override`: (optional) high level overrides to use when | 54 | * `security-override`: (optional) high level overrides to use when |
150 | 55 | `security-template` and `caps` are not | 55 | `security-template` and `caps` are not |
151 | 56 | sufficient. See security.md for details | 56 | sufficient. See security.md for details |
152 | 57 | * `security-policy`: (optional) hand-crafted low-level raw security | 57 | * `security-policy`: (optional) hand-crafted low-level raw security |
153 | 58 | policy to use instead of using default | 58 | policy to use instead of using default |
154 | 59 | template-based security policy. See | 59 | template-based security policy. See |
155 | 60 | security.md for details | 60 | security.md for details |
156 | 61 | * `ports`: (optional) define what ports the service will work | 61 | * `ports`: (optional) define what ports the service will work |
157 | 62 | * `internal`: the ports the service is going to connect to | 62 | * `internal`: the ports the service is going to connect to |
158 | 63 | * `tagname`: a free form name | 63 | * `tagname`: a free form name |
159 | 64 | * `port`: (optional) number/protocol, e.g. `80/tcp` | 64 | * `port`: (optional) number/protocol, e.g. `80/tcp` |
160 | 65 | * `negotiable`: (optional) Y if the app can use a different port | 65 | * `negotiable`: (optional) Y if the app can use a different port |
161 | 66 | * `external`: the ports the service offer to the world | 66 | * `external`: the ports the service offer to the world |
162 | 67 | * `tagname`: a free form name, some names have meaning like "ui" | 67 | * `tagname`: a free form name, some names have meaning like "ui" |
163 | 68 | * `port`: (optional) see above | 68 | * `port`: (optional) see above |
164 | 69 | * `negotiable`: (optional) see above | 69 | * `negotiable`: (optional) see above |
165 | 70 | * `bus-name`: (optional) message bus connection name for the service. | 70 | * `bus-name`: (optional) message bus connection name for the service. |
166 | 71 | May only be specified for snaps of 'type: framework' (see above). See | 71 | May only be specified for snaps of 'type: framework' (see above). See |
167 | 72 | frameworks.md for details. | 72 | frameworks.md for details. |
168 | 73 | 73 | ||
169 | 74 | * `binaries`: the binaries (executables) that the snap provides | 74 | * `binaries`: the binaries (executables) that the snap provides |
170 | 75 | * `name`: (required) the name of the binary, the user will be able to | 75 | * `name`: (required) the name of the binary, the user will be able to |
171 | 76 | call it as $name.$pkgname (only `[a-zA-Z0-9+.-]`) | 76 | call it as $name.$pkgname (only `[a-zA-Z0-9+.-]`) |
172 | 77 | * `exec`: the program that gets executed (can be omited if name points | 77 | * `exec`: the program that gets executed (can be omited if name points |
173 | 78 | to a binary already) | 78 | to a binary already) |
174 | 79 | * `caps`: (optional) see entry in `services` (above) | 79 | * `caps`: (optional) see entry in `services` (above) |
175 | 80 | * `security-template`: (optional) see entry in `services` (above) | 80 | * `security-template`: (optional) see entry in `services` (above) |
176 | 81 | * `security-override`: (optional) see entry in `services` (above) | 81 | * `security-override`: (optional) see entry in `services` (above) |
177 | 82 | * `security-policy`: (optional) see entry in `services` (above) | 82 | * `security-policy`: (optional) see entry in `services` (above) |
178 | 83 | 83 | ||
179 | 84 | ## license.txt | 84 | ## license.txt |
180 | 85 | 85 | ||
181 | 86 | 86 | ||
182 | === modified file 'docs/package-names.md' | |||
183 | --- docs/package-names.md 2015-04-15 22:03:57 +0000 | |||
184 | +++ docs/package-names.md 2015-05-19 14:28:51 +0000 | |||
185 | @@ -135,4 +135,4 @@ | |||
186 | 135 | becomes the gaming engine, you will need to be pushed out to a different name. | 135 | becomes the gaming engine, you will need to be pushed out to a different name. |
187 | 136 | 136 | ||
188 | 137 | ## Open questions | 137 | ## Open questions |
190 | 138 | * Must finalize what the `APP_ID` is going to be (composed? no devname? etc) | 138 | * Must finalize what the `APP_ID` is going to be (composed? no devname? etc) |
191 | 139 | 139 | ||
192 | === modified file 'docs/security.md' | |||
193 | --- docs/security.md 2015-05-12 15:32:03 +0000 | |||
194 | +++ docs/security.md 2015-05-19 14:28:51 +0000 | |||
195 | @@ -81,14 +81,14 @@ | |||
196 | 81 | Specify `caps: []` to indicate no additional `caps`. When `caps` and | 81 | Specify `caps: []` to indicate no additional `caps`. When `caps` and |
197 | 82 | `security-template` are not specified, `caps` defaults to client networking. | 82 | `security-template` are not specified, `caps` defaults to client networking. |
198 | 83 | Not compatible with `security-override` or `security-policy`. | 83 | Not compatible with `security-override` or `security-policy`. |
207 | 84 | * AppArmor access is deny by default and apps are restricted to their | 84 | * AppArmor access is deny by default and apps are restricted to |
208 | 85 | app-specific directories, libraries, etc (enforcing ro, rw, etc). | 85 | their app-specific directories, libraries, etc (enforcing ro, |
209 | 86 | Additional access beyond what is allowed by the declared `security-template` | 86 | rw, etc). Additional access beyond what is allowed by the |
210 | 87 | is declared via this option | 87 | declared `security-template` is declared via this option |
211 | 88 | * seccomp is deny by default. Enough safe syscalls are allowed so that apps | 88 | * seccomp is deny by default. Enough safe syscalls are allowed so |
212 | 89 | using the declared `security-template` should work. Additional access | 89 | that apps using the declared `security-template` should |
213 | 90 | beyond what is allowed by the `security-template` is declared via this | 90 | work. Additional access beyond what is allowed by the |
214 | 91 | option | 91 | `security-template` is declared via this option |
215 | 92 | * `security-template`: (optional) alternate security template to use instead of | 92 | * `security-template`: (optional) alternate security template to use instead of |
216 | 93 | `default`. When specified without `caps`, `caps` defaults to being empty. Not | 93 | `default`. When specified without `caps`, `caps` defaults to being empty. Not |
217 | 94 | compatible with `security-override` or `security-policy`. | 94 | compatible with `security-override` or `security-policy`. |
218 | @@ -97,13 +97,13 @@ | |||
219 | 97 | [advanced usage](https://wiki.ubuntu.com/SecurityTeam/Specifications/SnappyConfinement) | 97 | [advanced usage](https://wiki.ubuntu.com/SecurityTeam/Specifications/SnappyConfinement) |
220 | 98 | for details. Not compatible with `caps`, `security-template` or | 98 | for details. Not compatible with `caps`, `security-template` or |
221 | 99 | `security-policy` | 99 | `security-policy` |
224 | 100 | * `apparmor: path/to/security.override` | 100 | * `apparmor: path/to/security.override` |
225 | 101 | * `seccomp: path/to/filter.override` | 101 | * `seccomp: path/to/filter.override` |
226 | 102 | * `security-policy`: (optional) hand-crafted low-level raw security policy to | 102 | * `security-policy`: (optional) hand-crafted low-level raw security policy to |
227 | 103 | use instead of using default template-based security policy. Not compatible | 103 | use instead of using default template-based security policy. Not compatible |
228 | 104 | with `caps`, `security-template` or `security-override`. | 104 | with `caps`, `security-template` or `security-override`. |
231 | 105 | * `apparmor: path/to/profile` | 105 | * `apparmor: path/to/profile` |
232 | 106 | * `seccomp: path/to/filter` | 106 | * `seccomp: path/to/filter` |
233 | 107 | 107 | ||
234 | 108 | Eg, consider the following: | 108 | Eg, consider the following: |
235 | 109 | 109 | ||
236 | @@ -199,22 +199,22 @@ | |||
237 | 199 | The following is planned: | 199 | The following is planned: |
238 | 200 | 200 | ||
239 | 201 | * launcher: | 201 | * launcher: |
244 | 202 | * utilize syscall argument filtering | 202 | * utilize syscall argument filtering |
245 | 203 | * setup additional cgroups (tag network traffic, memory) | 203 | * setup additional cgroups (tag network traffic, memory) |
246 | 204 | * setup iptables using cgroup tags (for internal app access) | 204 | * setup iptables using cgroup tags (for internal app access) |
247 | 205 | * drop privileges to uid of service | 205 | * drop privileges to uid of service |
248 | 206 | * fine-grained network mediation via AppArmor | 206 | * fine-grained network mediation via AppArmor |
249 | 207 | * `sockets`: (optional) `AF_UNIX` abstract socket definition for coordinated | 207 | * `sockets`: (optional) `AF_UNIX` abstract socket definition for coordinated |
250 | 208 | snap communications. Abstract sockets will be namespaced and yaml is such | 208 | snap communications. Abstract sockets will be namespaced and yaml is such |
251 | 209 | that (client) apps wanting to use the socket don't have to declare anything | 209 | that (client) apps wanting to use the socket don't have to declare anything |
252 | 210 | extra, but they don't have access unless the (server) binary declaring the | 210 | extra, but they don't have access unless the (server) binary declaring the |
253 | 211 | socket says that app is ok). | 211 | socket says that app is ok). |
260 | 212 | * `names`: (optional) list of abstract socket names (`<name>_<binaryname>` is | 212 | * `names`: (optional) list of abstract socket names |
261 | 213 | prepended) | 213 | (`<name>_<binaryname>` is prepended) |
262 | 214 | * `allowed-clients`: `<name>.<namespace>` or `<name>.<namespace>_<binaryname>` | 214 | * `allowed-clients`: `<name>.<namespace>` or |
263 | 215 | (ie, omit version and `binaryname` to allow all from snap | 215 | `<name>.<namespace>_<binaryname>` (ie, omit version and |
264 | 216 | `<name>.<namespace>` or omit version to allow only `binaryname` from snap | 216 | `binaryname` to allow all from snap `<name>.<namespace>` or omit |
265 | 217 | `<name>`) | 217 | version to allow only `binaryname` from snap `<name>`) |
266 | 218 | 218 | ||
267 | 219 | Eg: | 219 | Eg: |
268 | 220 | 220 | ||
269 | 221 | 221 | ||
270 | === added file 'mdlint.py' | |||
271 | --- mdlint.py 1970-01-01 00:00:00 +0000 | |||
272 | +++ mdlint.py 2015-05-19 14:28:51 +0000 | |||
273 | @@ -0,0 +1,36 @@ | |||
274 | 1 | #!/usr/bin/python | ||
275 | 2 | # | ||
276 | 3 | # see http://daringfireball.net/projects/markdown/syntax | ||
277 | 4 | # for the "canonical" reference | ||
278 | 5 | # | ||
279 | 6 | # We support django-markdown which uses python-markdown, see: | ||
280 | 7 | # http://pythonhosted.org/Markdown/ | ||
281 | 8 | |||
282 | 9 | import sys | ||
283 | 10 | |||
284 | 11 | |||
285 | 12 | def lint_li(fname, text): | ||
286 | 13 | """Ensure that the list-items are multiplies of 4""" | ||
287 | 14 | is_clean = True | ||
288 | 15 | for i, line in enumerate(text.splitlines()): | ||
289 | 16 | if line.lstrip().startswith("*") and line.index("*") % 4 != 0: | ||
290 | 17 | print("%s: line %i list has non-4 spaces indent" % (fname, i)) | ||
291 | 18 | is_clean = False | ||
292 | 19 | return is_clean | ||
293 | 20 | |||
294 | 21 | |||
295 | 22 | def lint(md_files): | ||
296 | 23 | """lint all md files""" | ||
297 | 24 | all_clean = True | ||
298 | 25 | for md in md_files: | ||
299 | 26 | with open(md) as f: | ||
300 | 27 | buf = f.read() | ||
301 | 28 | for fname, func in globals().items(): | ||
302 | 29 | if fname.startswith("lint_"): | ||
303 | 30 | all_clean &= func(md, buf) | ||
304 | 31 | return all_clean | ||
305 | 32 | |||
306 | 33 | |||
307 | 34 | if __name__ == "__main__": | ||
308 | 35 | if not lint(sys.argv): | ||
309 | 36 | sys.exit(1) | ||
310 | 0 | 37 | ||
311 | === modified file 'run-checks' | |||
312 | --- run-checks 2015-03-27 18:35:24 +0000 | |||
313 | +++ run-checks 2015-05-19 14:28:51 +0000 | |||
314 | @@ -8,6 +8,9 @@ | |||
315 | 8 | goctest="go test" | 8 | goctest="go test" |
316 | 9 | fi | 9 | fi |
317 | 10 | 10 | ||
318 | 11 | echo Checking docs | ||
319 | 12 | ./mdlint.py docs/*.md | ||
320 | 13 | |||
321 | 11 | echo Checking formatting | 14 | echo Checking formatting |
322 | 12 | fmt=$(gofmt -l .) | 15 | fmt=$(gofmt -l .) |
323 | 13 | 16 |
This looks good, I wonder if we settle with markdown(django) that maybe we should move the rst doc to md as well, in a different MP that is.
I guess there is no such thing as a markdown(django) linter, this should do for this case. I added a teeny comment though.