Skip to content

Commit 79e78dd

Browse files
flexibeastflexibeast
committed
<various>: Reorganise content about contributing.
* Move contents of `style-guide` and `submitting` to `CONTRIBUTING`. * Move contents of `usage-statistics` to `contributing/index`. * Remove `style-guide`, `submitting`, `usage-statistics`. * Modify text of `CONTRIBUTING` appropriately. * Modify and improve text of `contributing/index`.
1 parent ecd8e2c commit 79e78dd

File tree

7 files changed

+361
-329
lines changed

7 files changed

+361
-329
lines changed

‎CONTRIBUTING.md

Lines changed: 326 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,328 @@
1-
To contribute to the Void documentation, please read the following sections of the Void Handbook. Pull requests that do not meet the criteria described in these sections will not be merged. Please try to address as many of the criteria as possible before submitting a PR - that will improve the chances of your contribution being accepted quickly.
1+
# Contributing
22

3-
- [About this Handbook](https://docs.voidlinux.org/about/about-this-handbook.html)
4-
- [Style Guide](https://docs.voidlinux.org/contributing/void-docs/style-guide.html)
5-
- [Submitting Changes](https://docs.voidlinux.org/contributing/void-docs/submitting.html)
3+
To contribute to the Void documentation, please read the following. Pull
4+
requests that do not meet the criteria described below will not be merged.
5+
Before submitting a PR:
66

7-
In particular, please be sure to run this repository's `check.sh` script, and to address any issues it raises, before submitting your PR.
7+
- try to address as many of the criteria as possible; and
8+
- run the `check.sh` script provided in the repository root, addressing any
9+
issues it reports.
10+
11+
This will improve the chances of your contribution being accepted quickly.
12+
13+
## Contents
14+
15+
- [Suitable Content](#suitable-content)
16+
- [Style Guide](#style-guide)
17+
- [Submitting Changes](#submitting-changes)
18+
19+
## Suitable content
20+
21+
The Handbook is not intended to be a general guide to using a Linux system, as
22+
[noted in the "About"
23+
section](https://docs.voidlinux.org/about/about-this-handbook.html):
24+
25+
> This handbook is not an extensive guide on how to use and configure common
26+
> Linux software. The purpose of this document is to explain how to install,
27+
> configure, and maintain Void Linux systems, and to highlight the differences
28+
> between common Linux distributions and Void ...
29+
>
30+
> Those looking for tips and tricks on how to configure a Linux system in
31+
> general should consult upstream software documentation. Additionally, the Arch
32+
> Wiki provides a fairly comprehensive outline of common Linux software
33+
> configuration, and a variety of internet search engines are available for
34+
> further assistance.
35+
36+
Thus, we are unlikely to accept contributions which add information that is not
37+
particularly Void-specific.
38+
39+
## Style Guide
40+
41+
This style guide outlines the standards for contributing to the Handbook. The
42+
manual on <https://docs.voidlinux.org> is generated from an
43+
[mdBook](https://rust-lang.github.io/mdBook/) stored in the
44+
[void-docs](https://github.com/void-linux/void-docs/) repository.
45+
46+
### General
47+
48+
Although there will always be cases where command listings are appropriate, the
49+
contents of the Handbook should be written in American English (or the relevant
50+
language in the case of translations of the Handbook).
51+
52+
Outside of the 'installation' sections, step-by-step instructions containing
53+
'magic' commands for copying-and-pasting are strongly discouraged. Users are
54+
expected to read the canonical documentation (e.g. man pages) for individual
55+
programs to understand how to use them, rather than relying on
56+
copying-and-pasting.
57+
58+
Command code-blocks should not be used to describe routine tasks documented
59+
elsewhere in this Handbook. For example, when writing documentation for the
60+
`foo` package, do not provide a command code-block stating that one should
61+
install it via `xbps-install foo`. Similarly, do not provide code blocks
62+
describing how to enable the `foo` service.
63+
64+
### Formatting
65+
66+
For markdown formatting, the
67+
[void-docs](https://github.com/void-linux/void-docs/) project uses the
68+
[Versioned Markdown](https://github.com/bobertlo/vmd) format, and enforces use
69+
of the auto-formatter `vmdfmt`, which works very similarly to `gofmt`. Most
70+
valid markdown is accepted by the formatter. The output format is described in
71+
the project's [README](https://github.com/bobertlo/vmd/blob/master/README.md).
72+
73+
After installing the `vmdfmt` package, you can format a file by running:
74+
75+
```
76+
vmdfmt -w <filepath>
77+
```
78+
79+
To format the entire mdbook from the repository root, outputting a list of files
80+
modified, run:
81+
82+
```
83+
vmdfmt -w -l <filepath>
84+
```
85+
86+
`vmdfmt` is used by the void-docs repository's `check.sh` script, which must be
87+
[run locally before submitting a pull request](#making-changes).
88+
89+
### Commands
90+
91+
Command code-blocks should start with a `#` or `$` character, indicating whether
92+
the command should be run as `root` or a regular user, respectively.
93+
94+
For example:
95+
96+
```
97+
# vi /etc/fstab
98+
```
99+
100+
and not:
101+
102+
```
103+
$ sudo vi /etc/fstab
104+
```
105+
106+
and also not:
107+
108+
```
109+
vi /etc/fstab
110+
```
111+
112+
Command code-blocks should be introduced with a colon (':'), i.e.:
113+
114+
> For example:
115+
>
116+
> `$ ls -l`
117+
118+
#### Placeholders
119+
120+
Placeholders indicate where the user should substitute the appropriate
121+
information. They should use angle brackets (`<` and `>`) and contain only
122+
lower-case text, with words separated by underscores. For example:
123+
124+
```
125+
# ln -s /etc/sv/<service_name> /var/service/
126+
```
127+
128+
and not:
129+
130+
```
131+
# ln -s /etc/sv/[SERVICENAME] /var/service/
132+
```
133+
134+
### Links
135+
136+
Link text should not include sentence-level punctuation. For example:
137+
138+
```
139+
[Visit this site](https://example.org).
140+
```
141+
142+
and not:
143+
144+
```
145+
[Visit this site.](https://example.org)
146+
```
147+
148+
#### Internal links
149+
150+
Links to other sections of the Handbook must be relative. For example:
151+
152+
```
153+
[example](./example.md#heading-text)
154+
```
155+
156+
and not:
157+
158+
```
159+
[example](example.md#heading-text)
160+
```
161+
162+
When referring literally to a Handbook section, the section title should be
163+
placed in double-quotes. Otherwise, double-quotes are not required. For example:
164+
165+
```
166+
For more information, please read the "[Power Management](./power-management.md)" section.
167+
```
168+
169+
and
170+
171+
```
172+
Void provides facilities to assist with [power management](./power-management.md).
173+
```
174+
175+
#### Man Page Links
176+
177+
The first reference to a command or man page must be a link to the relevant man
178+
page on `https://man.voidlinux.org/`.
179+
180+
The link text must contain the title section number in parenthesis, and contain
181+
no formatting. For example: [man(1)](https://man.voidlinux.org/man.1), not
182+
[`man(1)`](https://man.voidlinux.org/man.1).
183+
184+
#### Auto Links
185+
186+
Auto links (links with the same title as URL) should use the following notation:
187+
188+
```
189+
<https://www.example.com/>
190+
```
191+
192+
They should not be formatted like this:
193+
194+
```
195+
[https://www.example.com/](https://www.example.com/)
196+
```
197+
198+
#### Checking links
199+
200+
If you're including new links (either internal or external) in the docs or
201+
changing the current file structure, you should make use of the
202+
`mdbook-linkcheck` package:
203+
204+
```
205+
$ mdbook-linkcheck -s
206+
```
207+
208+
This will verify all the references, and warn you if there are any issues. If
209+
any link you're using is correct but generating errors for some reason, you can
210+
add its domain to the exclude list in `book.toml`, under the
211+
`[mdbook.linkcheck]` key.
212+
213+
`mdbook-linkcheck` is used by the void-docs repository's `check.sh` script,
214+
which must be [run locally before submitting a pull request](#making-changes).
215+
216+
### Case
217+
218+
Filenames and directories should use [kebab
219+
case](https://en.wikipedia.org/wiki/Kebab_case) when splitting words. For
220+
example the filename should be `post-install.md` not `postinstall.md`.
221+
222+
Words that are part of trademarks or well known package names are exempt from
223+
this rule. Examples include `PulseAudio` and `NetworkManager` which are well
224+
known by their squashed names.
225+
226+
### Voice
227+
228+
Prefer the active imperative voice when writing documentation. Consider the
229+
following examples:
230+
231+
> Now we need to install the CUPS drivers and configure them.
232+
233+
This version is conversational and friendlier, but contains unnecessary language
234+
that may not be as clear to an ESL reader.
235+
236+
> Install and configure the CUPS drivers, then configure them as shown.
237+
238+
This version contains a clear command to act, and a follow up that shows what
239+
will be done next. It is clear both to native English speakers, ESL readers, and
240+
to translators.
241+
242+
### Notes
243+
244+
Notes should only be used sparingly, and for non-critical information. They
245+
should begin with "Note: ", and not be block-quoted with `>`. For example, the
246+
Markdown should look like:
247+
248+
```
249+
Note: You can also use program X for this purpose.
250+
```
251+
252+
and not:
253+
254+
```
255+
> You can also use program X for this purpose.
256+
```
257+
258+
### Block quotes
259+
260+
Block quotes (i.e. `>`) should only be used to quote text from an external
261+
source.
262+
263+
## Submitting Changes
264+
265+
Proposed changes should be submitted as pull requests to the
266+
[void-docs](https://github.com/void-linux/void-docs) repository on
267+
[GitHub](https://github.com/). Please note that, unlike a wiki, submissions will
268+
be reviewed before they are merged. If any changes are required they will need
269+
to be made before the pull request is accepted. This process is in place to
270+
ensure the quality and standards of the Handbook are sustained.
271+
272+
### Requirements
273+
274+
To clone the repository and push changes,
275+
[git(1)](https://man.voidlinux.org/git.1) is required. It can be installed via
276+
the `git` package.
277+
278+
Building the Handbook locally requires
279+
[mdBook](https://rust-lang.github.io/mdBook/), which can be installed via the
280+
`mdBook` package.
281+
282+
### Forking
283+
284+
To fork the repository a [GitHub account](https://github.com/join) is needed.
285+
Once you have an account, follow GitHub's
286+
[guide](https://help.github.com/en/articles/fork-a-repo) on setting up a fork.
287+
288+
Clone the repository onto your computer, enter it, and create a new branch:
289+
290+
```
291+
$ git clone https://github.com/<your_username>/void-docs.git
292+
$ cd void-docs
293+
$ git checkout -b <branch_name>
294+
```
295+
296+
You can then edit the repository files as appropriate.
297+
298+
### Making changes
299+
300+
To serve the docs locally and view your changes, run `mdbook serve` from the
301+
root of the repository.
302+
303+
Once you're satisfied with your changes, run the `check.sh` script provided in
304+
the repository root. This will run the `vmdfmt` command, which will wrap the
305+
text appropriately, and the `mdbook-linkcheck` command, which will check for
306+
broken links. Address any issues raised by `check.sh`.
307+
308+
Once `check.sh` runs without errors, push your changes to your forked
309+
repository:
310+
311+
```
312+
$ git add <edited_file(s)>
313+
$ git commit -m "<commit_message>"
314+
$ git push --set-upstream origin <branch_name>
315+
```
316+
317+
The commit message should be in the form `<filename>: <description_of_changes>`.
318+
319+
Pull requests should only contain a single commit. If a change is made after the
320+
initial commit, `git add` the changed files and then run `git commit --amend`.
321+
The updated commit will need to be force-pushed: `git push --force`.
322+
323+
If multiple commits are made they will need to be squashed into a single commit
324+
with `git rebase -i HEAD~X`, where `X` is the number of commits that need to be
325+
squashed. An editor will appear to choose which commits to squash. A second
326+
editor will appear to choose the commit message. See
327+
[git-rebase(1)](https://man.voidlinux.org/git-rebase.1) for more information.
328+
The updated commit will need to be force-pushed: `git push --force`.

‎src/SUMMARY.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,4 @@
7171
- [Common Errors](./xbps/troubleshooting/common-errors.md)
7272
- [Static XBPS](./xbps/troubleshooting/static.md)
7373
- [Contributing](./contributing/index.md)
74-
- [Usage Statistics](./contributing/usage-statistics.md)
7574
- [Contributing To void-docs](./contributing/void-docs/index.md)
76-
- [Style Guide](./contributing/void-docs/style-guide.md)
77-
- [Submitting Changes](./contributing/void-docs/submitting.md)

‎src/contributing/index.md

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,36 @@
11
# Contributing
22

3-
There's more to running a distribution than just writing code. This section
4-
explains how to be an active part of Void.
3+
There's more to running a distribution than just writing code.
54

6-
Please also visit the Void Web site for further information about [how to
7-
participate](https://voidlinux.org/contribute/), including our communication
8-
channels and how to contribute to the Void package repository.
5+
To contribute to the Void packages repository, start by reading the
6+
[CONTRIBUTING](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
7+
document in the void-packages GitHub repository.
98

10-
## Section Contents
9+
To contribute to the Void Handbook, read
10+
[CONTRIBUTING](https://github.com/void-linux/void-docs/blob/master/CONTRIBUTING.md)
11+
in the void-docs GitHub repository.
1112

12-
- [Usage Statistics](./usage-statistics.md)
13-
- [Contributing To The void-docs Project](./void-docs/index.md)
13+
If you have any questions, feel free to ask them via IRC in #voidlinux on
14+
irc.freenode.net, or in [the voidlinux
15+
subreddit](https://reddit.com/r/voidlinux).
16+
17+
## Usage Statistics
18+
19+
If you would like to contribute usage reports, the
20+
[PopCorn](https://github.com/the-maldridge/popcorn) program reports installation
21+
statistics back to the Void project. These statistics are purely opt-in -
22+
PopCorn is *not* installed or enabled by default on any Void systems.
23+
24+
*PopCorn* only reports which packages are installed, their version, and the host
25+
CPU architecture (the output of `xuname`). This does not report which services
26+
are enabled, or any other personal information. Individual systems are tracked
27+
persistently by a random (client-generated) UUID, to ensure that each system is
28+
only counted once in each 24-hour sampling period.
29+
30+
The data collected by *PopCorn* is available to view at
31+
<http://popcorn.voidlinux.org>
32+
33+
### Setting up PopCorn
34+
35+
First, install the `PopCorn` package. Then, enable the `popcorn` service, which
36+
will attempt to report statistics once per day.

0 commit comments

Comments
 (0)