Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: announce our docs website to the world + instructions to contribute #2239

Merged
merged 3 commits into from
Sep 12, 2023
Merged

README: announce our docs website to the world + instructions to contribute #2239

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7a481e9
README: point users to the new documentation website
ilyagr Sep 9, 2023
a6dd84d
README: Edits to Getting Started
ilyagr Sep 9, 2023
306e90f
contributing.md: add section about contributing to the docs
ilyagr Sep 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 47 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,17 +21,21 @@ or the [recording](https://www.youtube.com/watch?v=bx_LGilOuE4).

## Introduction

Jujutsu is a [Git-compatible](docs/git-compatibility.md)
Jujutsu is a
[Git-compatible](https://martinvonz.github.io/jj/latest/git-compatibility)
[DVCS](https://en.wikipedia.org/wiki/Distributed_version_control). It combines
features from Git (data model,
[speed](https://github.com/martinvonz/jj/discussions/49)), Mercurial (anonymous
branching, simple CLI [free from "the index"](docs/git-comparison.md#the-index),
[revsets](docs/revsets.md), powerful history-rewriting), and Pijul/Darcs
([first-class conflicts](docs/conflicts.md)), with features not found in most
of them ([working-copy-as-a-commit](docs/working-copy.md),
[undo functionality](docs/operation-log.md), automatic rebase,
[safe replication via `rsync`, Dropbox, or distributed file
system](docs/technical/concurrency.md)).
branching, simple CLI [free from "the
index"](https://martinvonz.github.io/jj/latest/git-comparison#the-index),
[revsets](https://martinvonz.github.io/jj/latest/revsets), powerful
history-rewriting), and Pijul/Darcs ([first-class
conflicts](https://martinvonz.github.io/jj/latest/conflicts)), with features not
found in most of them
([working-copy-as-a-commit](https://martinvonz.github.io/jj/latest/working-copy),
[undo functionality](https://martinvonz.github.io/jj/latest/operation-log),
automatic rebase, [safe replication via `rsync`, Dropbox, or distributed file
system](https://martinvonz.github.io/jj/latest/technical/concurrency)).

The command-line tool is called `jj` for now because it's easy to type and easy
to replace (rare in English). The project is called "Jujutsu" because it matches
Expand All @@ -40,30 +44,41 @@ to replace (rare in English). The project is called "Jujutsu" because it matches
If you have any questions, please join us on Discord
[![Discord](https://img.shields.io/discord/968932220549103686.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/dkmfj3aGQN)
or start a [GitHub Discussion](https://github.com/martinvonz/jj/discussions).
The [glossary](docs/glossary.md) may also be helpful.


## Getting started

Follow the [installation instructions](docs/install-and-setup.md) to obtain and configure `jj`.
Follow the [installation
instructions](https://martinvonz.github.io/jj/latest/install-and-setup) to
obtain and configure `jj`.

The best way to get started is probably to go through [the
tutorial](https://martinvonz.github.io/jj/latest/tutorial). Also see the [Git
comparison](https://martinvonz.github.io/jj/latest/git-comparison), which
includes a table of `jj` vs. `git` commands.

As you become more familiar with Jujutsu, the following resources may be helpful:

The best way to get started is probably to go through
[the tutorial](docs/tutorial.md). Also see the
[Git comparison](docs/git-comparison.md), which includes a table of
`jj` vs. `git` commands.
- The [FAQ](https://martinvonz.github.io/jj/latest/FAQ).
- The [Glossary](https://martinvonz.github.io/jj/latest/glossary).
- The `jj help` command (e.g. `jj help rebase`).

As you become more familiar with Jujutsu, the [FAQ](docs/FAQ.md) may help.
If you are using a **prerelease** version of `jj`, you would want to consult
[the docs for the prerelease (main branch)
version](https://martinvonz.github.io/jj/prerelease/). You can also get there
from the docs for the latest release by using the website's version switcher. The version switcher is visible in
the header of the website when you scroll to the top of any page.


## Features
ilyagr marked this conversation as resolved.
Show resolved Hide resolved

### Compatible with Git

Jujutsu has two [backends](docs/glossary.md#backend). One of them is a Git
backend (the other is a native one [^native-backend]). This lets you use Jujutsu
as an alternative interface to Git. The commits you create will look like
regular Git commits. You can always switch back to Git. The Git support uses the
[libgit2](https://libgit2.org/) C library.
Jujutsu has two
[backends](https://martinvonz.github.io/jj/latest/glossary#backend). One of them
is a Git backend (the other is a native one [^native-backend]). This lets you
use Jujutsu as an alternative interface to Git. The commits you create will look
like regular Git commits. You can always switch back to Git. The Git support
uses the [libgit2](https://libgit2.org/) C library.

[^native-backend]: At this time, there's practically no reason to use the native
backend. The backend exists mainly to make sure that it's possible to eventually
Expand All @@ -72,8 +87,8 @@ add functionality that cannot easily be added to the Git backend.
<img src="demos/git_compat.png" />

You can even have a ["co-located" local
repository](docs/git-compatibility.md#co-located-jujutsugit-repos) where you can
use both `jj` and `git` commands interchangeably.
repository](https://martinvonz.github.io/jj/latest/git-compatibility#co-located-jujutsugit-repos)
where you can use both `jj` and `git` commands interchangeably.

### The working copy is automatically committed

Expand Down Expand Up @@ -112,13 +127,14 @@ necessarily have to be the most recent operation).

### Conflicts can be recorded in commits

If an operation results in [conflicts](docs/glossary.md#conflict), information
about those conflicts will be recorded in the commit(s). The operation will
succeed. You can then resolve the conflicts later. One consequence of this
design is that there's no need to continue interrupted operations. Instead, you
get a single workflow for resolving conflicts, regardless of which command
caused them. This design also lets Jujutsu rebase merge commits correctly
(unlike both Git and Mercurial).
If an operation results in
[conflicts](https://martinvonz.github.io/jj/latest/glossary#conflict),
information about those conflicts will be recorded in the commit(s). The
operation will succeed. You can then resolve the conflicts later. One
consequence of this design is that there's no need to continue interrupted
operations. Instead, you get a single workflow for resolving conflicts,
regardless of which command caused them. This design also lets Jujutsu rebase
merge commits correctly (unlike both Git and Mercurial).

Basic conflict resolution:

Expand Down Expand Up @@ -163,4 +179,4 @@ scripts if requested.
## Related work

There are several tools trying to solve similar problems as Jujutsu. See
[related work](docs/related-work.md) for details.
[related work](https://martinvonz.github.io/jj/latest/related-work) for details.
38 changes: 31 additions & 7 deletions docs/contributing.md
View file
Open in desktop
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
<command>` docs. If a part of the bug report template does not apply, you can
just delete it.

Before reporting 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 requires 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