Skip to content

Commit

Permalink
contributing.md: add section about contributing to the docs
Browse files Browse the repository at this point in the history
  • Loading branch information
ilyagr committed Sep 9, 2023
1 parent 28e2a4d commit 706347c
Showing 1 changed file with 31 additions and 7 deletions.
38 changes: 31 additions & 7 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,17 +58,42 @@ This project follows [Google's Open Source Community
Guidelines](https://opensource.google/conduct/).


## Contributing to the documentation

We appreciate [bug
reports](https://github.com/martinvonz/jj/issues/new?template=bug_report.md)
about any problems, however small, lurking in [our documentation
website](https://martinvonz.github.io/jj/prerelease) or in the `jj help` docs.
If a part of the bug report template does not apply, you can just delete it.

Before reporting or working on a problem with the documentation website, we'd
appreciate it if you could check that the problem still exists in the
"prerelease" version of the documentation (as opposed to the docs for one of the
released versions of `jj`). You can use the version switcher in the top-left of
the website to do so.

If you are willing to make a PR fixing a documentation problem, even better!

The documentation website sources are Markdown files located in the [`docs/`
directory](https://github.com/martinvonz/jj/tree/main/docs). You do not need to
know Rust to work with them. See below for [instructions on how to preview the
HTML docs](#previewing-the-html-documentation) as you edit the Markdown files.
Doing so is optional, but recommended.

The `jj help` docs are sourced from the "docstring" comments inside the Rust
sources, currently from the [`cli/src/commands`
directory](https://github.com/martinvonz/jj/tree/main/cli/src/commands). Working
on them does require setting up a Rust development environment, as described
below, and may occasionally require adjusting a test.


## Learning Rust

In addition to the [Rust Book](https://doc.rust-lang.org/book/) and the other
excellent resources at <https://www.rust-lang.org/learn>, we recommend the
["Comprehensive Rust" mini-course](https://google.github.io/comprehensive-rust/)
for an overview, especially if you are familiar with C++.

<!--- TODO: A section asking for people to report documentation bugs and
---- asking them to check if the problem exists in the prerelease docs.
---->

## Setting up a development environment

To develop `jj`, the mandatory steps are simply
Expand Down Expand Up @@ -137,9 +162,8 @@ These are listed roughly in order of decreasing importance.

## Previewing the HTML documentation

The documentation for `jj` is automatically published to the website
<https://martinvonz.github.io/jj/>. At the moment, this is experimental,
but we hope to advertise this website to our users soon.
The documentation for `jj` is automatically published to the website at
<https://martinvonz.github.io/jj/>.

When editing documentation, we'd appreciate it if you checked that the
result will look as expected when published to the website.
Expand Down

0 comments on commit 706347c

Please sign in to comment.