ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity
jj/v0.9.0/contributing.html
Ilya Grigoriev f67d6a192c docs SEO (direct website push): Use "latest" URL as canonical URL for older versions 
The replacement was done by `sed`.

This should only change versions of the docs prior to 864869ab (in
particular, not the `latest` version nor the `prerelease` version), and
make it as though the old version of the docs were compiled with that
commit. It tries to solve the same problem:
https://www.google.com/search?q=jj+revsets still points to jj v0.13
docs.

Google seems really slow to update its index, and I'm beginning to worry
that it might think we have a spammy site with many almost identical
pages. I hope it will pick up this change once it tries to update its
crawl of pages it's already indexing.

Loosely related reading: https://news.ycombinator.com/item?id=40970987
2024-07-25 14:29:08 -07:00

1580 lines
No EOL
44 KiB
HTML
Raw Blame History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link rel="canonical" href="https://martinvonz.github.io/jj/latest/contributing.html">
<link rel="prev" href="technical/conflicts.html">
<link rel="next" href="code-of-conduct.html">
<link rel="icon" href="assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.5.2, mkdocs-material-9.2.5">
<title>Guidelines and "How to...?" - Jujutsu docs</title>
<link rel="stylesheet" href="assets/stylesheets/main.0e669242.min.css">
<script src="https://unpkg.com/iframe-worker/shim"></script>
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL(".",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr">
<script>var palette=__md_get("__palette");if(palette&&"object"==typeof palette.color)for(var key of Object.keys(palette.color))document.body.setAttribute("data-md-color-"+key,palette.color[key])</script>
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#how-to-contribute" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<div data-md-color-scheme="default" data-md-component="outdated" hidden>
</div>
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="." title="Jujutsu docs" class="md-header__button md-logo" aria-label="Jujutsu docs" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
Jujutsu docs
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Guidelines and "How to...?"
</span>
</div>
</div>
</div>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="." title="Jujutsu docs" class="md-nav__button md-logo" aria-label="Jujutsu docs" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg>
</a>
Jujutsu docs
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" >
<label class="md-nav__link" for="__nav_1" id="__nav_1_label" tabindex="0">
<span class="md-ellipsis">
Getting started
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_1">
<span class="md-nav__icon md-icon"></span>
Getting started
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="install-and-setup.html" class="md-nav__link">
<span class="md-ellipsis">
Installation and Setup
</span>
</a>
</li>
<li class="md-nav__item">
<a href="tutorial.html" class="md-nav__link">
<span class="md-ellipsis">
Tutorial and Birds-Eye View
</span>
</a>
</li>
<li class="md-nav__item">
<a href="github.html" class="md-nav__link">
<span class="md-ellipsis">
Working with GitHub
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="FAQ.html" class="md-nav__link">
<span class="md-ellipsis">
FAQ
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
<span class="md-ellipsis">
Concepts
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Concepts
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="working-copy.html" class="md-nav__link">
<span class="md-ellipsis">
Working Copy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="branches.html" class="md-nav__link">
<span class="md-ellipsis">
Branches
</span>
</a>
</li>
<li class="md-nav__item">
<a href="conflicts.html" class="md-nav__link">
<span class="md-ellipsis">
Conflicts
</span>
</a>
</li>
<li class="md-nav__item">
<a href="operation-log.html" class="md-nav__link">
<span class="md-ellipsis">
Operation Log
</span>
</a>
</li>
<li class="md-nav__item">
<a href="glossary.html" class="md-nav__link">
<span class="md-ellipsis">
Glossary
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
<span class="md-ellipsis">
Configuration
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
Configuration
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="config.html" class="md-nav__link">
<span class="md-ellipsis">
Settings
</span>
</a>
</li>
<li class="md-nav__item">
<a href="revsets.html" class="md-nav__link">
<span class="md-ellipsis">
Revset language
</span>
</a>
</li>
<li class="md-nav__item">
<a href="templates.html" class="md-nav__link">
<span class="md-ellipsis">
Templating language
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-ellipsis">
Comparisons
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Comparisons
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="git-comparison.html" class="md-nav__link">
<span class="md-ellipsis">
Git comparison
</span>
</a>
</li>
<li class="md-nav__item">
<a href="git-compatibility.html" class="md-nav__link">
<span class="md-ellipsis">
Git compatibility
</span>
</a>
</li>
<li class="md-nav__item">
<a href="sapling-comparison.html" class="md-nav__link">
<span class="md-ellipsis">
Sapling
</span>
</a>
</li>
<li class="md-nav__item">
<a href="related-work.html" class="md-nav__link">
<span class="md-ellipsis">
Other related work
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" >
<label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
<span class="md-ellipsis">
Technical details
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
Technical details
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="technical/architecture.html" class="md-nav__link">
<span class="md-ellipsis">
Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="technical/concurrency.html" class="md-nav__link">
<span class="md-ellipsis">
Concurrency
</span>
</a>
</li>
<li class="md-nav__item">
<a href="technical/conflicts.html" class="md-nav__link">
<span class="md-ellipsis">
Conflicts
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" checked>
<label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0">
<span class="md-ellipsis">
Contributing
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_7">
<span class="md-nav__icon md-icon"></span>
Contributing
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Guidelines and "How to...?"
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="contributing.html" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Guidelines and "How to...?"
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#policies" class="md-nav__link">
Policies
</a>
<nav class="md-nav" aria-label="Policies">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#contributor-license-agreement" class="md-nav__link">
Contributor License Agreement
</a>
</li>
<li class="md-nav__item">
<a href="#code-reviews" class="md-nav__link">
Code reviews
</a>
</li>
<li class="md-nav__item">
<a href="#community-guidelines" class="md-nav__link">
Community Guidelines
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#learning-rust" class="md-nav__link">
Learning Rust
</a>
</li>
<li class="md-nav__item">
<a href="#setting-up-a-development-environment" class="md-nav__link">
Setting up a development environment
</a>
<nav class="md-nav" aria-label="Setting up a development environment">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#summary" class="md-nav__link">
Summary
</a>
</li>
<li class="md-nav__item">
<a href="#explanation" class="md-nav__link">
Explanation
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#previewing-the-html-documentation" class="md-nav__link">
Previewing the HTML documentation
</a>
<nav class="md-nav" aria-label="Previewing the HTML documentation">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#setting-up-the-prerequisites" class="md-nav__link">
Setting up the prerequisites
</a>
</li>
<li class="md-nav__item">
<a href="#building-the-html-docs-locally-with-live-reload" class="md-nav__link">
Building the HTML docs locally (with live reload)
</a>
</li>
<li class="md-nav__item">
<a href="#how-to-build-the-entire-website-not-usually-necessary" class="md-nav__link">
How to build the entire website (not usually necessary)
</a>
<nav class="md-nav" aria-label="How to build the entire website (not usually necessary)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#explanation-of-the-docs-build-deploy-script" class="md-nav__link">
Explanation of the docs-build-deploy script
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#modifying-protobuffers-this-is-not-common" class="md-nav__link">
Modifying protobuffers (this is not common)
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="code-of-conduct.html" class="md-nav__link">
<span class="md-ellipsis">
Code of conduct
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" >
<label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex="0">
<span class="md-ellipsis">
Design docs
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_8">
<span class="md-nav__icon md-icon"></span>
Design docs
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="design/git-submodules.html" class="md-nav__link">
<span class="md-ellipsis">
git-submodules
</span>
</a>
</li>
<li class="md-nav__item">
<a href="design/git-submodule-storage.html" class="md-nav__link">
<span class="md-ellipsis">
git-submodule-storage
</span>
</a>
</li>
<li class="md-nav__item">
<a href="design/tracking-branches.html" class="md-nav__link">
<span class="md-ellipsis">
Tracking branches
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#policies" class="md-nav__link">
Policies
</a>
<nav class="md-nav" aria-label="Policies">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#contributor-license-agreement" class="md-nav__link">
Contributor License Agreement
</a>
</li>
<li class="md-nav__item">
<a href="#code-reviews" class="md-nav__link">
Code reviews
</a>
</li>
<li class="md-nav__item">
<a href="#community-guidelines" class="md-nav__link">
Community Guidelines
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#learning-rust" class="md-nav__link">
Learning Rust
</a>
</li>
<li class="md-nav__item">
<a href="#setting-up-a-development-environment" class="md-nav__link">
Setting up a development environment
</a>
<nav class="md-nav" aria-label="Setting up a development environment">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#summary" class="md-nav__link">
Summary
</a>
</li>
<li class="md-nav__item">
<a href="#explanation" class="md-nav__link">
Explanation
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#previewing-the-html-documentation" class="md-nav__link">
Previewing the HTML documentation
</a>
<nav class="md-nav" aria-label="Previewing the HTML documentation">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#setting-up-the-prerequisites" class="md-nav__link">
Setting up the prerequisites
</a>
</li>
<li class="md-nav__item">
<a href="#building-the-html-docs-locally-with-live-reload" class="md-nav__link">
Building the HTML docs locally (with live reload)
</a>
</li>
<li class="md-nav__item">
<a href="#how-to-build-the-entire-website-not-usually-necessary" class="md-nav__link">
How to build the entire website (not usually necessary)
</a>
<nav class="md-nav" aria-label="How to build the entire website (not usually necessary)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#explanation-of-the-docs-build-deploy-script" class="md-nav__link">
Explanation of the docs-build-deploy script
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#modifying-protobuffers-this-is-not-common" class="md-nav__link">
Modifying protobuffers (this is not common)
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="how-to-contribute">How to Contribute<a class="headerlink" href="#how-to-contribute" title="Permanent link">&para;</a></h1>
<h2 id="policies">Policies<a class="headerlink" href="#policies" title="Permanent link">&para;</a></h2>
<p>We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.</p>
<h3 id="contributor-license-agreement">Contributor License Agreement<a class="headerlink" href="#contributor-license-agreement" title="Permanent link">&para;</a></h3>
<p>Contributions to this project must be accompanied by a Contributor License
Agreement. You (or your employer) retain the copyright to your contribution;
this simply gives us permission to use and redistribute your contributions as
part of the project. Head over to <a href="https://cla.developers.google.com/">https://cla.developers.google.com/</a> to see
your current agreements on file or to sign a new one.</p>
<p>You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.</p>
<h3 id="code-reviews">Code reviews<a class="headerlink" href="#code-reviews" title="Permanent link">&para;</a></h3>
<p>All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
<a href="https://help.github.com/articles/about-pull-requests/">GitHub Help</a> for more
information on using pull requests.</p>
<p>Unlike many GitHub projects (but like many VCS projects), we care more about the
contents of commits than about the contents of PRs. We review each commit
separately, and we don't squash-merge the PR (so please manually squash any
fixup commits before sending for review).</p>
<p>Each commit should ideally do one thing. For example, if you need to refactor a
function in order to add a new feature cleanly, put the refactoring in one
commit and the new feature in a different commit. If the refactoring itself
consists of many parts, try to separate out those into separate commits. You can
use <code>jj split</code> to do it if you didn't realize ahead of time how it should be
split up. Include tests and documentation in the same commit as the code the
test and document. The commit message should describe the changes in the commit;
the PR description can even be empty, but feel free to include a personal
message.</p>
<p>When you address comments on a PR, don't make the changes in a commit on top (as
is typical on GitHub). Instead, please make the changes in the appropriate
commit. You can do that by checking out the commit (<code>jj checkout/new &lt;commit&gt;</code>)
and then squash in the changes when you're done (<code>jj squash</code>). <code>jj git push</code>
will automatically force-push the branch.</p>
<p>When your first PR has been approved, we typically give you contributor access,
so you can address any remaining minor comments and then merge the PR yourself
when you're ready. If you realize that some comments require non-trivial
changes, please ask your reviewer to take another look.</p>
<h3 id="community-guidelines">Community Guidelines<a class="headerlink" href="#community-guidelines" title="Permanent link">&para;</a></h3>
<p>This project follows <a href="https://opensource.google/conduct/">Google's Open Source Community
Guidelines</a>.</p>
<h2 id="learning-rust">Learning Rust<a class="headerlink" href="#learning-rust" title="Permanent link">&para;</a></h2>
<p>In addition to the <a href="https://doc.rust-lang.org/book/">Rust Book</a> and the other
excellent resources at <a href="https://www.rust-lang.org/learn">https://www.rust-lang.org/learn</a>, we recommend the
<a href="https://google.github.io/comprehensive-rust/">"Comprehensive Rust" mini-course</a>
for an overview, especially if you are familiar with C++.</p>
<!--- TODO: A section asking for people to report documentation bugs and
---- asking them to check if the problem exists in the prerelease docs.
---->
<h2 id="setting-up-a-development-environment">Setting up a development environment<a class="headerlink" href="#setting-up-a-development-environment" title="Permanent link">&para;</a></h2>
<p>To develop <code>jj</code>, the mandatory steps are simply
to <a href="https://www.rust-lang.org/tools/install">install Rust</a> (the default
installer options are fine), clone the repository, and use <code>cargo build</code>
, <code>cargo fmt</code>,
<code>cargo clippy --workspace --all-targets</code>, and
<code>cargo test --workspace</code>. If you are preparing a PR, there are some additional
recommended steps.</p>
<h3 id="summary">Summary<a class="headerlink" href="#summary" title="Permanent link">&para;</a></h3>
<p>One-time setup:</p>
<div class="codehilite"><pre><span></span><code>rustup toolchain add nightly # wanted for &#39;rustfmt&#39;
rustup toolchain add 1.71 # also specified in Cargo.toml
cargo install cargo-insta
cargo install cargo-watch
cargo install cargo-nextest
</code></pre></div>
<p>During development (adapt according to your preference):</p>
<div class="codehilite"><pre><span></span><code>cargo watch --ignore &#39;.jj/**&#39; -s \
&#39;cargo clippy --workspace --all-targets \
&amp;&amp; cargo +1.71 check --workspace --all-targets&#39;
cargo +nightly fmt # Occasionally
cargo nextest run --workspace # Occasionally
cargo insta test --workspace --test-runner nextest # Occasionally
</code></pre></div>
<p>WARNING: Build artifacts from debug builds and especially from repeated
invocations of <code>cargo test</code> can quickly take up 10s of GB of disk space.
Cargo will happily use up your entire hard drive. If this happens, run
<code>cargo clean</code>.</p>
<h3 id="explanation">Explanation<a class="headerlink" href="#explanation" title="Permanent link">&para;</a></h3>
<p>These are listed roughly in order of decreasing importance.</p>
<ol>
<li>
<p>Nearly any change to <code>jj</code>'s CLI will require writing or updating snapshot
tests that use the <a href="https://insta.rs/"><code>insta</code></a> crate. To make this
convenient, install the <code>cargo-insta</code> binary.
Use <code>cargo insta test --workspace</code> to run tests,
and <code>cargo insta review --workspace</code> to update the snapshot tests.
The <code>--workspace</code> flag is needed to run the tests on all crates; by default,
only the crate in the current directory is tested.</p>
</li>
<li>
<p>GitHub CI checks require that the code is formatted with the <em>nightly</em>
version of <code>rustfmt</code>. To do this on your computer, install the nightly
toolchain and use <code>cargo +nightly fmt</code>.</p>
</li>
<li>
<p>Your code will be rejected if it cannot be compiled with the minimal
supported version of Rust ("MSRV"). Currently, <code>jj</code> follows a rather
casual MSRV policy: "The current <code>rustc</code> stable version, minus one."
As of this writing, that version is <strong>1.71.0</strong>.</p>
</li>
<li>
<p>Your code needs to pass <code>cargo clippy</code>. You can also
use <code>cargo +nightly clippy</code> if you wish to see more warnings.</p>
</li>
<li>
<p>You may also want to install and use <code>cargo-watch</code>. In this case, you should
exclude <code>.jj</code>. directory from the filesystem watcher, as it gets updated on
every <code>jj log</code>.</p>
</li>
<li>
<p>To run tests more quickly, use <code>cargo nextest run --workspace</code>. To
use <code>nextest</code> with <code>insta</code>,
use <code>cargo insta test --workspace --test-runner nextest</code>.</p>
</li>
</ol>
<h2 id="previewing-the-html-documentation">Previewing the HTML documentation<a class="headerlink" href="#previewing-the-html-documentation" title="Permanent link">&para;</a></h2>
<p>The documentation for <code>jj</code> is automatically published to the website
<a href="https://martinvonz.github.io/jj/">https://martinvonz.github.io/jj/</a>. At the moment, this is experimental,
but we hope to advertise this website to our users soon.</p>
<p>When editing documentation, we'd appreciate it if you checked that the
result will look as expected when published to the website.</p>
<h3 id="setting-up-the-prerequisites">Setting up the prerequisites<a class="headerlink" href="#setting-up-the-prerequisites" title="Permanent link">&para;</a></h3>
<p>To build the website, you must have Python and <code>poetry</code> installed. If
your distribution packages <code>poetry</code>, something like <code>apt install
python3-poetry</code> is likely the best way to install it. Otherwise, you
can download Python from <a href="https://python.org">https://python.org</a> or follow the <a href="https://docs.python.org/3/using/index.html">Python
installation instructions</a>. Finally, follow the <a href="https://python-poetry.org/docs/#installation">Poetry installation
instructions</a>.</p>
<p>Once you have <code>poetry</code> installed, you should ask it to install the rest
of the required tools into a virtual environment as follows:</p>
<div class="highlight"><pre><span></span><code>poetry<span class="w"> </span>install
</code></pre></div>
<p>If you get requests to "unlock a keyring" or error messages about failing to do
so, this is a <a href="https://github.com/python-poetry/poetry/issues/1917">known <code>poetry</code>
bug</a>. The workaround is to
run the following and then to try <code>poetry install</code> again:</p>
<div class="highlight"><pre><span></span><code><span class="c1"># For sh-compatible shells or recent versions of `fish`</span>
<span class="nb">export</span><span class="w"> </span><span class="nv">PYTHON_KEYRING_BACKEND</span><span class="o">=</span>keyring.backends.fail.Keyring
</code></pre></div>
<h3 id="building-the-html-docs-locally-with-live-reload">Building the HTML docs locally (with live reload)<a class="headerlink" href="#building-the-html-docs-locally-with-live-reload" title="Permanent link">&para;</a></h3>
<p>The HTML docs are built with <a href="https://github.com/mkdocs/mkdocs">MkDocs</a>. After
following the above steps, you should be able to view the docs by running</p>
<div class="highlight"><pre><span></span><code><span class="c1"># Note: this and all the commands below should be run from the root of</span>
<span class="c1"># the `jj` source tree.</span>
poetry<span class="w"> </span>run<span class="w"> </span>--<span class="w"> </span>mkdocs<span class="w"> </span>serve
</code></pre></div>
<p>and opening <a href="http://127.0.0.1:8000">http://127.0.0.1:8000</a> in your browser.</p>
<p>As you edit the <code>md</code> files, the website should be rebuilt and reloaded in your
browser automatically, unless build errors occur.</p>
<p>You should occasionally check the terminal from which you ran <code>mkdocs serve</code> for
any build errors or warnings. Warnings about <code>"GET /versions.json HTTP/1.1" code
404</code> are expected and harmless.</p>
<h3 id="how-to-build-the-entire-website-not-usually-necessary">How to build the entire website (not usually necessary)<a class="headerlink" href="#how-to-build-the-entire-website-not-usually-necessary" title="Permanent link">&para;</a></h3>
<p>The full <code>jj</code> website includes the documentation for several <code>jj</code> versions
(<code>prerelease</code>, latest release, and the older releases). The top-level
URL <a href="https://martinvonz.github.io/jj">https://martinvonz.github.io/jj</a> redirects to
<a href="https://martinvonz.github.io/jj/latest">https://martinvonz.github.io/jj/latest</a>, which in turn redirects to
the docs for the last stable version.</p>
<p>The different versions of documentation are managed and deployed with
<a href="https://github.com/jimporter/mike"><code>mike</code></a>, which can be run with
<code>poetry run -- mike</code>.</p>
<p>On a POSIX system or WSL, one way to build the entire website is as follows (on
Windows, you'll need to understand and adapt the shell script):</p>
<ol>
<li>
<p>Check out <code>jj</code> as a co-located <code>jj + git</code> repository (<code>jj clone --colocate</code>),
cloned from your fork of <code>jj</code> (e.g. <code>jjfan.github.com/jj</code>). You can also use a
pure Git repo if you prefer.</p>
</li>
<li>
<p>Make sure <code>jjfan.github.com/jj</code> includes the <code>gh-pages</code> branch of the jj repo
and run <code>git fetch origin gh-pages</code>.</p>
</li>
<li>
<p>Go to the GitHub repository settings, enable GitHub Pages, and configure them
to use the <code>gh-pages</code> branch (this is usually the default).</p>
</li>
<li>
<p>Run the same <code>sh</code> script that is used in GitHub CI (details below):</p>
<div class="highlight"><pre><span></span><code>.github/scripts/docs-build-deploy<span class="w"> </span><span class="s1">&#39;https://jjfan.github.io/jj/&#39;</span><span class="se">\</span>
<span class="w"> </span>prerelease<span class="w"> </span>main<span class="w"> </span>--push
</code></pre></div>
<p>This should build the version of the docs from the current commit,
deploy it as a new commit to the <code>gh-pages</code> branch,
and push the <code>gh-pages</code> branch to the origin.</p>
</li>
<li>
<p>Now, you should be able to see the full website, including your latest changes
to the <code>prerelease</code> version, at <code>https://jjfan.github.io/jj/prerelease/</code>.</p>
</li>
<li>
<p>(Optional) The previous steps actually only rebuild
<code>https://jjfan.github.io/jj/prerelease/</code> and its alias
<code>https://jjfan.github.io/jj/main/</code>. If you'd like to test out version switching
back and forth, you can also rebuild the docs for the latest release as follows.</p>
<div class="highlight"><pre><span></span><code>jj<span class="w"> </span>new<span class="w"> </span>v1.33.1<span class="w"> </span><span class="c1"># Let&#39;s say `jj 1.33.1` is the currently the latest release</span>
.github/scripts/docs-build-deploy<span class="w"> </span><span class="s1">&#39;https://jjfan.github.io/jj/&#39;</span><span class="se">\</span>
<span class="w"> </span>v1.33.1<span class="w"> </span>latest<span class="w"> </span>--push
</code></pre></div>
</li>
<li>
<p>(Optional) When you are done, you may want to reset the <code>gh-branches</code> to the
same spot as it is in the upstream. If you configured the <code>upstream</code> remote,
this can be done with:</p>
<div class="highlight"><pre><span></span><code><span class="c1"># This will LOSE any changes you made to `gh-pages`</span>
jj<span class="w"> </span>git<span class="w"> </span>fetch<span class="w"> </span>--remote<span class="w"> </span>upstream
jj<span class="w"> </span>branch<span class="w"> </span><span class="nb">set</span><span class="w"> </span>gh-pages<span class="w"> </span>-r<span class="w"> </span>gh-pages@upstream
jj<span class="w"> </span>git<span class="w"> </span>push<span class="w"> </span>--remote<span class="w"> </span>origin<span class="w"> </span>--branch<span class="w"> </span>gh-pages
</code></pre></div>
<p>If you want to preserve some of the changes you made, you can do <code>jj branch
set my-changes -r gh-pages</code> BEFORE running the above commands.</p>
</li>
</ol>
<h4 id="explanation-of-the-docs-build-deploy-script">Explanation of the <code>docs-build-deploy</code> script<a class="headerlink" href="#explanation-of-the-docs-build-deploy-script" title="Permanent link">&para;</a></h4>
<p>The script sets up the <code>site_url</code> mkdocs config to
<code>'https://jjfan.github.io/jj/'</code>. If this config does not match the URL
where you loaded the website, some minor website features (like the
version switching widget) will have reduced functionality.</p>
<p>Then, the script passes the rest of its arguments to <code>potery run -- mike
deploy</code>, which does the rest of the job. Run <code>poetry run -- mike help deploy</code> to
find out what the arguments do.</p>
<p>If you need to do something more complicated, you can use <code>poetry run -- mike
...</code> commands. You can also edit the <code>gh-pages</code> branch directly, but take care
to avoid files that will be overwritten by future invocations of <code>mike</code>. Then,
you can submit a PR based on the <code>gh-pages</code> branch of
<a href="https://martinvonz.github.com/jj">https://martinvonz.github.com/jj</a> (instead of the usual <code>main</code> branch).</p>
<h2 id="modifying-protobuffers-this-is-not-common">Modifying protobuffers (this is not common)<a class="headerlink" href="#modifying-protobuffers-this-is-not-common" title="Permanent link">&para;</a></h2>
<p>Occasionally, you may need to change the <code>.proto</code> files that define jj's data
storage format. In this case, you will need to add a few steps to the above
workflow.</p>
<ul>
<li>Install the <code>protoc</code> compiler. This usually means either <code>apt-get install
protobuf-compiler</code> or downloading <a href="https://github.com/protocolbuffers/protobuf/releases">an official release</a>. The
<code>prost</code> <a href="https://docs.rs/prost-build/latest/prost_build/#sourcing-protoc">library docs</a> have additional advice.</li>
<li>Run <code>cargo run -p gen-protos</code> regularly (or after every edit to a <code>.proto</code>
file). This is the same as running <code>cargo run</code> from <code>lib/gen-protos</code>. The
<code>gen-protos</code> binary will use the <code>prost-build</code> library to compile the
<code>.proto</code> files into <code>.rs</code> files.</li>
<li>If you are adding a new <code>.proto</code> file, you will need to edit the list of
these files in <code>lib/gen-protos/src/main.rs</code>.</li>
</ul>
<p>The <code>.rs</code> files generated from <code>.proto</code> files are included in the repository,
and there is a GitHub CI check that will complain if they do not match.</p>
</article>
</div>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": ".", "features": [], "search": "assets/javascripts/workers/search.dfff1995.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"provider": "mike"}}</script>
<script src="assets/javascripts/bundle.78eede0e.min.js"></script>
</body>
</html>
View git blame Copy permalink