docs: Display `main` branch name as inline code.

Signed-off-by: Anders Kaseorg <anders@zulip.com>
This commit is contained in:
Anders Kaseorg 2021-08-31 18:13:20 -07:00 committed by Anders Kaseorg
parent 646c04eff2
commit f4d2d199e2
17 changed files with 53 additions and 53 deletions

View File

@ -28,7 +28,7 @@ to dive right into reviewing the PR's core functionality.
Once you've received a review and resolved any feedback, it's critical Once you've received a review and resolved any feedback, it's critical
to update the GitHub thread to reflect that. Best practices are to: to update the GitHub thread to reflect that. Best practices are to:
* Make sure that CI passes and the PR is rebased onto recent main. * Make sure that CI passes and the PR is rebased onto recent `main`.
* Post comments on each feedback thread explaining at least how you * Post comments on each feedback thread explaining at least how you
resolved the feedback, as well as any other useful information resolved the feedback, as well as any other useful information
(problems encountered, reasoning for why you picked one of several (problems encountered, reasoning for why you picked one of several
@ -215,7 +215,7 @@ Some points specific to the Zulip server codebase:
To make it easier to review pull requests, if you're working in the To make it easier to review pull requests, if you're working in the
Zulip server codebase, use our [git tool] Zulip server codebase, use our [git tool]
`tools/fetch-rebase-pull-request` to check out a pull request locally `tools/fetch-rebase-pull-request` to check out a pull request locally
and rebase it against main. and rebase it onto `main`.
If a pull request just needs a little fixing to make it mergeable, If a pull request just needs a little fixing to make it mergeable,
feel free to do that in a new commit, then push your branch to GitHub feel free to do that in a new commit, then push your branch to GitHub

View File

@ -445,7 +445,7 @@ guide][rtd-git-guide].
If after rebasing onto a new version of the Zulip server, you receive If after rebasing onto a new version of the Zulip server, you receive
new errors while starting the Zulip server or running tests, this is new errors while starting the Zulip server or running tests, this is
probably not because Zulip's main branch is broken. Instead, this probably not because Zulip's `main` branch is broken. Instead, this
is likely because we've recently merged changes to the development is likely because we've recently merged changes to the development
environment provisioning process that you need to apply to your environment provisioning process that you need to apply to your
development environment. To update your environment, you'll need to development environment. To update your environment, you'll need to

View File

@ -13,7 +13,7 @@ the development environment][authentication-dev-server].
## Common ## Common
* Zulip's main branch moves quickly, and you should rebase * Zulip's `main` branch moves quickly, and you should rebase
constantly with e.g. `git fetch upstream; git rebase constantly with e.g. `git fetch upstream; git rebase
upstream/main` to avoid developing on an old version of the Zulip upstream/main` to avoid developing on an old version of the Zulip
codebase (leading to unnecessary merge conflicts). codebase (leading to unnecessary merge conflicts).

View File

@ -84,7 +84,7 @@ See also [fixing commits][fix-commit]
- `git log`: show commit logs - `git log`: show commit logs
- `git log --oneline | head`: To quickly see the latest ten commits on a branch. - `git log --oneline | head`: To quickly see the latest ten commits on a branch.
- pull - pull
- `git pull --rebase`: rebase your changes on top of main. - `git pull --rebase`: rebase your changes on top of `main`.
- `git pull` (with no options): Will either create a merge commit - `git pull` (with no options): Will either create a merge commit
(which you don't want) or do the same thing as `git pull --rebase`, (which you don't want) or do the same thing as `git pull --rebase`,
depending on [whether you've configured Git properly][git-config-clone] depending on [whether you've configured Git properly][git-config-clone]
@ -94,8 +94,8 @@ See also [fixing commits][fix-commit]
- `git push origin +branch-name`: force push your commits to your origin repository. - `git push origin +branch-name`: force push your commits to your origin repository.
- rebase - rebase
- `git rebase -i HEAD~3`: interactive rebasing current branch with first three items on HEAD - `git rebase -i HEAD~3`: interactive rebasing current branch with first three items on HEAD
- `git rebase -i main`: interactive rebasing current branch with main branch - `git rebase -i main`: interactive rebasing current branch with `main` branch
- `git rebase upstream/main`: rebasing current branch with main branch from upstream repository - `git rebase upstream/main`: rebasing current branch with `main` branch from upstream repository
- reflog - reflog
- `git reflog | head -10`: manage reference logs for the past 10 commits - `git reflog | head -10`: manage reference logs for the past 10 commits
- remote - remote

View File

@ -43,19 +43,19 @@ $ git diff e2f404c 7977169
## Changes between branches ## Changes between branches
Display changes between tip of topic branch and tip of main branch: Display changes between tip of `topic` branch and tip of `main` branch:
```console ```console
$ git diff topic main $ git diff topic main
``` ```
Display changes that have occurred on main branch since topic branch was created: Display changes that have occurred on `main` branch since `topic` branch was created:
```console ```console
$ git diff topic...main $ git diff topic...main
``` ```
Display changes you've committed so far since creating a branch from upstream/main: Display changes you've committed so far since creating a branch from `upstream/main`:
```console ```console
$ git diff upstream/main...HEAD $ git diff upstream/main...HEAD

View File

@ -153,7 +153,7 @@ which ever branch you are rebasing on top of, is to code that has been changed
by those new commits. by those new commits.
For example, while I'm working on a file, another contributor makes a change to For example, while I'm working on a file, another contributor makes a change to
that file, submits a pull request and has their code merged into main. that file, submits a pull request and has their code merged into `main`.
Usually this is not a problem, but in this case the other contributor made a Usually this is not a problem, but in this case the other contributor made a
change to a part of the file I also want to change. When I try to bring my change to a part of the file I also want to change. When I try to bring my
branch up to date with `git fetch` and then `git rebase upstream/main`, I see branch up to date with `git fetch` and then `git rebase upstream/main`, I see

View File

@ -67,7 +67,7 @@ Switched to branch 'main'
$ git rebase upstream/main $ git rebase upstream/main
``` ```
This will rollback any changes you've made to main, update it from This will rollback any changes you've made to `main`, update it from
`upstream/main`, and then re-apply your changes. Rebasing keeps the commit `upstream/main`, and then re-apply your changes. Rebasing keeps the commit
history clean and readable. history clean and readable.
@ -99,10 +99,10 @@ feature. Recall from [how Git is different][how-git-is-different] that
**Git is designed for lightweight branching and merging.** You can and should **Git is designed for lightweight branching and merging.** You can and should
create as many branches as you'd like. create as many branches as you'd like.
First, make sure your main branch is up-to-date with Zulip upstream ([see First, make sure your `main` branch is up-to-date with Zulip upstream ([see
how][zulip-git-guide-up-to-date]). how][zulip-git-guide-up-to-date]).
Next, from your main branch, create a new tracking branch, providing a Next, from your `main` branch, create a new tracking branch, providing a
descriptive name for your feature branch: descriptive name for your feature branch:
```console ```console
@ -317,7 +317,7 @@ testing in a more production-like environment.
The final paragraph indicates that this commit addresses and fixes issue #1755. The final paragraph indicates that this commit addresses and fixes issue #1755.
When you submit your pull request, GitHub will detect and link this reference When you submit your pull request, GitHub will detect and link this reference
to the appropriate issue. Once your commit is merged into zulip/main, GitHub to the appropriate issue. Once your commit is merged into `upstream/main`, GitHub
will automatically close the referenced issue. See [Closing issues via commit will automatically close the referenced issue. See [Closing issues via commit
messages][github-help-closing-issues] for details. messages][github-help-closing-issues] for details.
@ -335,7 +335,7 @@ This ensures your work is backed up should something happen to your local
machine and allows others to follow your progress. It also allows you to machine and allows others to follow your progress. It also allows you to
[work from multiple computers][self-multiple-computers] without losing work. [work from multiple computers][self-multiple-computers] without losing work.
Pushing to a feature branch is just like pushing to main: Pushing to a feature branch is just like pushing to `main`:
```console ```console
$ git push origin <branch-name> $ git push origin <branch-name>

View File

@ -31,7 +31,7 @@ Sometimes you want to publish commits. Here are some scenarios:
Finally, the Zulip core team will occasionally want your changes! Finally, the Zulip core team will occasionally want your changes!
- The Zulip core team can accept your changes and add them to - The Zulip core team can accept your changes and add them to
the official repo, usually on the main branch. the official repo, usually on the `main` branch.
## Relevant Git commands ## Relevant Git commands

View File

@ -70,7 +70,7 @@ HEAD is now at 2bcd1d8 troubleshooting tip about provisioning
`tools/fetch-rebase-pull-request` is a short-cut for [checking out a pull `tools/fetch-rebase-pull-request` is a short-cut for [checking out a pull
request locally][zulip-git-guide-fetch-pr] in its own branch and then updating it with any request locally][zulip-git-guide-fetch-pr] in its own branch and then updating it with any
changes from upstream/main with `git rebase`. changes from `upstream/main` with `git rebase`.
Run the script with the ID number of the pull request as the first argument. Run the script with the ID number of the pull request as the first argument.
@ -96,7 +96,7 @@ Current branch review-1913 is up to date.
## Fetch a pull request without rebasing ## Fetch a pull request without rebasing
`tools/fetch-pull-request` is a similar to `tools/fetch-rebase-pull-request`, but `tools/fetch-pull-request` is a similar to `tools/fetch-rebase-pull-request`, but
it does not rebase the pull request against upstream/main, thereby getting it does not rebase the pull request against `upstream/main`, thereby getting
exactly the same repository state as the commit author had. exactly the same repository state as the commit author had.
Run the script with the ID number of the pull request as the first argument. Run the script with the ID number of the pull request as the first argument.
@ -146,8 +146,8 @@ achieve this by granting other users permission to write to your fork.
`tools/clean-branches` is a shell script that removes branches that are either: `tools/clean-branches` is a shell script that removes branches that are either:
1. Local branches that are ancestors of origin/main. 1. Local branches that are ancestors of `origin/main`.
2. Branches in origin that are ancestors of origin/main and named like `$USER-*`. 2. Branches in origin that are ancestors of `origin/main` and named like `$USER-*`.
3. Review branches created by `tools/fetch-rebase-pull-request` and `tools/fetch-pull-request`. 3. Review branches created by `tools/fetch-rebase-pull-request` and `tools/fetch-pull-request`.
First, make sure you are working in branch `main`. Then run the script without any First, make sure you are working in branch `main`. Then run the script without any
@ -164,7 +164,7 @@ Deleting local branch review-original-5156 (was 5a1e982)
If there is a merge conflict on yarn.lock, yarn should be run to If there is a merge conflict on yarn.lock, yarn should be run to
regenerate the file. *Important* don't delete the yarn.lock file. Check out the regenerate the file. *Important* don't delete the yarn.lock file. Check out the
latest one from origin/main so that yarn knows the previous asset versions. latest one from `origin/main` so that yarn knows the previous asset versions.
Run the following commands Run the following commands
```bash ```bash

View File

@ -470,7 +470,7 @@ log][commit-log] for an up-to-date list of raw changes.
was actually an integration for canarytokens.org). was actually an integration for canarytokens.org).
- Reformatted the frontend codebase using prettier. This change was - Reformatted the frontend codebase using prettier. This change was
included in this maintenance release to ensure backporting patches included in this maintenance release to ensure backporting patches
from main remains easy. from `main` remains easy.
### 3.0 -- July 16, 2020 ### 3.0 -- July 16, 2020

View File

@ -60,25 +60,25 @@ the Zulip server itself (E.g. `https://zulip.example.com/help/`).
Many Zulip servers run versions from Git that have not been published Many Zulip servers run versions from Git that have not been published
in a stable release. in a stable release.
* [Zulip Cloud](https://zulip.com) essentially runs the main * [Zulip Cloud](https://zulip.com) essentially runs the `main`
branch. It is usually a few days behind main (with some branch. It is usually a few days behind `main` (with some
cherry-picked bug fixes), but can fall up to 2 weeks behind when cherry-picked bug fixes), but can fall up to 2 weeks behind when
major UI or internals changes mean we'd like to bake changes longer major UI or internals changes mean we'd like to bake changes longer
on chat.zulip.org before exposing them to the full Zulip Cloud on chat.zulip.org before exposing them to the full Zulip Cloud
userbase. userbase.
* [chat.zulip.org][chat-zulip-org], the bleeding-edge server for the * [chat.zulip.org][chat-zulip-org], the bleeding-edge server for the
Zulip development community, is upgraded to main several times Zulip development community, is upgraded to `main` several times
every week. We also often "test deploy" changes not yet in main every week. We also often "test deploy" changes not yet in `main`
to chat.zulip.org to facilitate design feedback. to chat.zulip.org to facilitate design feedback.
* We maintain Git branches with names like `4.x` containing backported * We maintain Git branches with names like `4.x` containing backported
commits from main that we plan to include in the next maintenance commits from `main` that we plan to include in the next maintenance
release. Self hosters can [upgrade][upgrade-from-git] to these release. Self hosters can [upgrade][upgrade-from-git] to these
stable release branches to get bug fixes staged for the next stable stable release branches to get bug fixes staged for the next stable
release (which is very useful when you reported a bug whose fix we release (which is very useful when you reported a bug whose fix we
choose to backport). We support these branches as though they were a choose to backport). We support these branches as though they were a
stable release. stable release.
* Self-hosters who want new features not yet present in a major * Self-hosters who want new features not yet present in a major
release can [upgrade to main][upgrading-to-main] or run [a fork release can [upgrade to `main`][upgrading-to-main] or run [a fork
of Zulip][fork-zulip]. of Zulip][fork-zulip].
### Compatibility and upgrading ### Compatibility and upgrading

View File

@ -304,7 +304,7 @@ archive of all the organization's uploaded files.
version of Zulip as the server you're exporting from. version of Zulip as the server you're exporting from.
* For exports from Zulip Cloud (zulip.com), you need to [upgrade to * For exports from Zulip Cloud (zulip.com), you need to [upgrade to
main][upgrade-zulip-from-git], since we run run main on `main`][upgrade-zulip-from-git], since we run run `main` on
Zulip Cloud: Zulip Cloud:
```bash ```bash

View File

@ -10,7 +10,7 @@ This page explains how to upgrade, patch, or modify Zulip, including:
- [Upgrading the operating system](#upgrading-the-operating-system) - [Upgrading the operating system](#upgrading-the-operating-system)
- [Upgrading PostgreSQL](#upgrading-postgresql) - [Upgrading PostgreSQL](#upgrading-postgresql)
- [Modifying Zulip](#modifying-zulip) - [Modifying Zulip](#modifying-zulip)
- [Applying changes from main](#applying-changes-from-main) - [Applying changes from `main`](#applying-changes-from-main)
## Upgrading to a release ## Upgrading to a release
@ -68,7 +68,7 @@ run into any issues or need to roll back the upgrade.
Zulip supports upgrading a production installation to any commit in a Zulip supports upgrading a production installation to any commit in a
Git repository, which is great for [running pre-release changes from Git repository, which is great for [running pre-release changes from
main](#applying-changes-from-main) or [maintaining a `main`](#applying-changes-from-main) or [maintaining a
fork](#making-changes). The process is simple: fork](#making-changes). The process is simple:
```bash ```bash
@ -89,7 +89,7 @@ were a published release.
The `main` branch contains changes planned for the next major The `main` branch contains changes planned for the next major
release (E.g. 3.0); see our documentation on [running release (E.g. 3.0); see our documentation on [running
main](#upgrading-to-main) before upgrading to it. `main`](#upgrading-to-main) before upgrading to it.
By default, this uses the main upstream Zulip server repository, but By default, this uses the main upstream Zulip server repository, but
you can configure any other Git repository by adding a section like you can configure any other Git repository by adding a section like
@ -527,7 +527,7 @@ that fact:
are related to the issue, just mention your changes in the issue report. are related to the issue, just mention your changes in the issue report.
If you're looking to modify Zulip by applying changes developed by the If you're looking to modify Zulip by applying changes developed by the
Zulip core team and merged into main, skip to [this Zulip core team and merged into `main`, skip to [this
section](#applying-changes-from-main). section](#applying-changes-from-main).
## Making changes ## Making changes
@ -599,9 +599,9 @@ Eventually, you'll want to upgrade to a new Zulip release. If your
changes were integrated into that Zulip release or are otherwise no changes were integrated into that Zulip release or are otherwise no
longer needed, you can just [upgrade as longer needed, you can just [upgrade as
usual](#upgrading-to-a-release). If you [upgraded to usual](#upgrading-to-a-release). If you [upgraded to
main](#upgrading-to-main); review that section again; new `main`](#upgrading-to-main); review that section again; new
maintenance releases are likely "older" than your current installation maintenance releases are likely "older" than your current installation
and you might need to upgrade to the main again rather than to the and you might need to upgrade to `main` again rather than to the
new maintenance release. new maintenance release.
Otherwise, you'll need to update your branch by rebasing your changes Otherwise, you'll need to update your branch by rebasing your changes
@ -640,7 +640,7 @@ different from the above:
[docker-zulip]: https://github.com/zulip/docker-zulip [docker-zulip]: https://github.com/zulip/docker-zulip
[docker-zulip-upgrade]: https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository [docker-zulip-upgrade]: https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository
## Applying changes from main ## Applying changes from `main`
If you are experiencing an issue that has already been fixed by the If you are experiencing an issue that has already been fixed by the
Zulip development community, and you'd like to get the fix now, you Zulip development community, and you'd like to get the fix now, you
@ -662,7 +662,7 @@ of the change you'd like).
In general, we can't provide unpaid support for issues caused by In general, we can't provide unpaid support for issues caused by
cherry-picking arbitrary commits if the issues don't also affect cherry-picking arbitrary commits if the issues don't also affect
main or an official release. `main` or an official release.
The exception to this rule is when we ask or encourage a user to apply The exception to this rule is when we ask or encourage a user to apply
a change to their production system to help verify the fix resolves a change to their production system to help verify the fix resolves
@ -676,14 +676,14 @@ addition to scheduling that change for Zulip's next bug fix release,
we support changes in stable release branches as though they were we support changes in stable release branches as though they were
released. released.
### Upgrading to main ### Upgrading to `main`
Many Zulip servers (including chat.zulip.org and zulip.com) upgrade to Many Zulip servers (including chat.zulip.org and zulip.com) upgrade to
main on a regular basis to get the latest features. Before doing `main` on a regular basis to get the latest features. Before doing
so, it's important to understand how to happily run a server based on so, it's important to understand how to happily run a server based on
main. `main`.
For background, it's backporting arbitrary patches from main to an For background, it's backporting arbitrary patches from `main` to an
older version requires some care. Common issues include: older version requires some care. Common issues include:
* Changes containing database migrations (new files under * Changes containing database migrations (new files under
@ -698,8 +698,8 @@ unlikely to succeed without help from the core team via a support
contract. contract.
If you need an unreleased feature, the best path is usually to If you need an unreleased feature, the best path is usually to
upgrade to Zulip main using [upgrade-zulip-from-git][]. Before upgrade to Zulip `main` using [upgrade-zulip-from-git][]. Before
upgrading to main, make sure you understand: upgrading to `main`, make sure you understand:
* In Zulip's version numbering scheme, `main` will always be "newer" * In Zulip's version numbering scheme, `main` will always be "newer"
than the latest maintenance release (E.g. `3.1` or `2.1.6`) and than the latest maintenance release (E.g. `3.1` or `2.1.6`) and
@ -717,7 +717,7 @@ upgrading to main, make sure you understand:
be stable. Most regressions will be minor UX issues or be fixed be stable. Most regressions will be minor UX issues or be fixed
quickly, because we need them to be fixed for Zulip Cloud. quickly, because we need them to be fixed for Zulip Cloud.
* The development community is very interested in helping debug issues * The development community is very interested in helping debug issues
that arise when upgrading from the latest release to main, since that arise when upgrading from the latest release to `main`, since
they provide us an opportunity to fix that category of issue before they provide us an opportunity to fix that category of issue before
our next major release. (Much more so than we are in helping folks our next major release. (Much more so than we are in helping folks
debug other custom changes). That said, we cannot make any debug other custom changes). That said, we cannot make any
@ -733,9 +733,9 @@ upgrading to main, make sure you understand:
since the last release. The **Upgrade notes** section will always since the last release. The **Upgrade notes** section will always
be current, even if some new features aren't documented. be current, even if some new features aren't documented.
* Whenever we push a security or maintenance release, the changes in * Whenever we push a security or maintenance release, the changes in
that release will always be merged to main; so you can get the that release will always be merged to `main`; so you can get the
security fixes by upgrading to main. security fixes by upgrading to `main`.
* You can always upgrade from main to the next major release when it * You can always upgrade from `main` to the next major release when it
comes out, using either [upgrade-zulip-from-git][] or the release comes out, using either [upgrade-zulip-from-git][] or the release
tarball. So there's no risk of upgrading to `main` resulting in tarball. So there's no risk of upgrading to `main` resulting in
a system that's not upgradeable back to a normal release. a system that's not upgradeable back to a normal release.

View File

@ -333,7 +333,7 @@ usually one needs to think about making changes in 3 places:
to be called from `tools/update-prod-static`, which is called by to be called from `tools/update-prod-static`, which is called by
`tools/build-release-tarball` (for doing Zulip releases) as well as `tools/build-release-tarball` (for doing Zulip releases) as well as
`tools/upgrade-zulip-from-git` (for deploying a Zulip server off of `tools/upgrade-zulip-from-git` (for deploying a Zulip server off of
main). `main`).
[virtualenv]: https://virtualenv.pypa.io/en/stable/ [virtualenv]: https://virtualenv.pypa.io/en/stable/
[virtualenv-clone]: https://github.com/edwardgeorge/virtualenv-clone/ [virtualenv-clone]: https://github.com/edwardgeorge/virtualenv-clone/

View File

@ -43,7 +43,7 @@ preparing a new release.
### Executing the release ### Executing the release
* Create the release commit, on main (for major releases) or on the * Create the release commit, on `main` (for major releases) or on the
release branch (for minor releases): release branch (for minor releases):
* Copy the Markdown release notes for the release into * Copy the Markdown release notes for the release into
`docs/overview/changelog.md`. `docs/overview/changelog.md`.
@ -79,7 +79,7 @@ preparing a new release.
* Create a release branch (e.g. `4.x`). * Create a release branch (e.g. `4.x`).
* On the release branch, update `ZULIP_VERSION` in `version.py` to * On the release branch, update `ZULIP_VERSION` in `version.py` to
the present release with a `+git` suffix, e.g. `4.0+git`. the present release with a `+git` suffix, e.g. `4.0+git`.
* On main, update `ZULIP_VERSION` to the future major release with * On `main`, update `ZULIP_VERSION` to the future major release with
a `-dev+git` suffix, e.g. `5.0-dev+git`. Make a Git tag for this a `-dev+git` suffix, e.g. `5.0-dev+git`. Make a Git tag for this
update commit with a `-dev` suffix, e.g. `5.0-dev`. Push the tag update commit with a `-dev` suffix, e.g. `5.0-dev`. Push the tag
to both zulip.git and zulip-internal.git to get a correct version to both zulip.git and zulip-internal.git to get a correct version

View File

@ -137,7 +137,7 @@ notes above:
verify it does not fail nondeterminstically (see above for notes on verify it does not fail nondeterminstically (see above for notes on
how to get CI to do it for you); this is important to avoid how to get CI to do it for you); this is important to avoid
introducing extremely annoying nondeterministic failures into introducing extremely annoying nondeterministic failures into
main. `main`.
- With black-box browser tests like these, it's very important to write your code - With black-box browser tests like these, it's very important to write your code
to wait for browser's UI to update before taking any action that to wait for browser's UI to update before taking any action that
assumes the last step was processed by the browser (E.g. after you assumes the last step was processed by the browser (E.g. after you

View File

@ -61,7 +61,7 @@ to any languages that you'd like to contribute to (or add new ones).
1. If possible, test your translations (details below). 1. If possible, test your translations (details below).
1. Ask in Zulip for a maintainer to sync the strings from Transifex, 1. Ask in Zulip for a maintainer to sync the strings from Transifex,
merge them to main, and deploy the update to chat.zulip.org so merge them to `main`, and deploy the update to chat.zulip.org so
you can verify them in action there. you can verify them in action there.
Some useful tips for your translating journey: Some useful tips for your translating journey: