# Contributing

Before making any changes,
please discuss your plans on GitHub
and get agreement on the general direction of the change.

## Making changes

- style.md is generated from the contents of the src/ folder.
  All changes must be made to files in the src/ folder.
- For new entries, create a new file with a short name
  (see [File names](#file-names)) and add it to [SUMMARY.md](src/SUMMARY.md).
  The file must have a single level 1 heading and any number of subsections.
- Use tables for side-by-side code samples.
- Link to other sections with their file names (`[..](foo.md)`).

## Updating style.md

`style.md` is generated from the contents of `src/` using [stitchmd](https://github.com/abhinav/stitchmd).
If CI fails because `style.md` is out of date, regenerate it by running:

```bash
make
```

This will install `stitchmd` if needed and update `style.md`.
Commit the result and push it to your branch.

## Writing style

### Line breaks

Use [semantic line breaks](https://sembr.org/) in your writing.
This keeps the Markdown files easily reviewable and editable.

### File names

Files in src/ follow a rough naming convention of:

    {subject}-{desc}.md

Where `{subject}` is the **singular form** of subject that the entry is about
(e.g `string`, `struct`, `time`, `var`, `error`)
and `{desc}` is a short one or two word description of the topic.
For subjects where their name is enough, the `-{desc}` may be omitted.

### Code samples

Use two spaces to indent code samples.
Horizontal space is limited in side-by-side samples.

### Side-by-side samples

Create side-by-side code samples with the following template:

~~~
<table>
<thead><tr><th>Bad</th><th>Good</th></tr></thead>
<tbody>
<tr><td>

```go
BAD CODE GOES HERE
```

</td><td>

```go
GOOD CODE GOES HERE
```

</td></tr>
</tbody></table>
~~~

The empty lines between the HTML tags and code samples are necessary.

If you need to add labels or descriptions below the code samples,
add another row before the `</tbody></table>` line.

~~~
<tr>
<td>DESCRIBE BAD CODE</td>
<td>DESCRIBE GOOD CODE</td>
</tr>
~~~