mirror of
https://github.com/angular/angular
synced 2026-05-24 09:28:37 +00:00
6c98ca4572
This update describes the content authoring and revision process in sufficient detail for technical and non-technical contributors to the angular.io documentation. PR Close #47381
175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
# Start to edit a documentation topic
|
|
|
|
<!-- markdownLint-disable MD001 -->
|
|
|
|
This topic describes the tasks that you perform when you start to work on a documentation issue.
|
|
|
|
The documentation in angular.io is built from [markdown](https://en.wikipedia.org/wiki/Markdown) source code files.
|
|
The markdown source code files are stored in the `angular` repo that you forked into your GitHub account.
|
|
|
|
To update the Angular documentation, you need:
|
|
|
|
* A clone of `personal/angular`
|
|
|
|
You created this when you [created your workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer).
|
|
Before you start editing a topic, [update your clone of `personal/angular`](#update-your-fork-with-the-upstream-repo).
|
|
|
|
* A `working` branch that you create from an up-to-date `main` branch.
|
|
|
|
Creating your `working` branch is described [later in this topic](#create-a-working-branch-for-editing).
|
|
|
|
<!-- markdownLint-disable MD033 -->
|
|
|
|
The procedures in this topic assume that the files on your local computer are organized as illustrated in the following diagram. On your local computer, you should have:
|
|
|
|
* Your 'git' workspace directory.
|
|
In this example, the path to your 'git' workspace directory is `github-projects`.
|
|
|
|
* Your working directory, which is the directory that you created when you cloned your fork into your `git` workspace.
|
|
In this example, the path to your working directory is `github-projects/personal/angular`, where `personal` is replaced with your GitHub username.
|
|
|
|
<div class="lightbox">
|
|
|
|
<!-- Image source is found in angular/aio/src/assets/images/doc-contribute-images.sketch, in the sketch page that matches this topic's filename -->
|
|
<img alt="An image of the working directories on a local computer" src="generated/images/guide/doc-update-start/pc-directory-config.png">
|
|
|
|
</div>
|
|
|
|
<div class="alert is-important">
|
|
|
|
**IMPORTANT**: <br />
|
|
Remember to replace `personal` with your GitHub username in the commands and examples in this topic.
|
|
|
|
</div>
|
|
|
|
The procedures in this topic assume that you are starting from your workspace directory.
|
|
|
|
## Update your fork with the upstream repo
|
|
|
|
Before you start editing the documentation files, you want to sync the `main` branch of your fork and its clone with the `main` branch of the upstream `angular/angular` repo.
|
|
|
|
This procedure updates the your `personal/angular` repo in the cloud and its clone on your local computer, as illustrated here.
|
|
The circled numbers correspond to procedure steps.
|
|
|
|
<div class="lightbox">
|
|
|
|
<!-- Image source is found in angular/aio/src/assets/images/doc-contribute-images.sketch, in the sketch page that matches this topic's filename -->
|
|
<img alt="An image of the git fetch/merge/push process used to update the local computer" src="generated/images/guide/doc-update-start/github-fetch-merge.png">
|
|
|
|
</div>
|
|
|
|
#### To update your fork and its clone with the upstream repo
|
|
|
|
Perform these steps from a command-line tool on your local computer.
|
|
|
|
1. From your [workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer) directory, run this command to navigate to your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
|
|
This step is not shown in the image.
|
|
Remember to replace `personal` with your GitHub username.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
cd personal/angular
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to check out the `main` branch.
|
|
This step is not shown in the image.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
git checkout main
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to update the `main` branch in the working directory on your local computer from the upstream `angular/angular` repo.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
git fetch upstream
|
|
git merge upstream/main
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to update your `personal/angular` repo on `github.com` with the latest from the upstream `angular/angular` repo.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
git push
|
|
|
|
</code-example>
|
|
|
|
The `main` branch on your local computer is now in sync with your origin repo on `github.com`.
|
|
They have been updated with any changes that have been made to the upstream `angular/angular` repo since the last time you updated your fork.
|
|
|
|
## Create a working branch for editing
|
|
|
|
All your edits to the Angular documentation are made in a `working` branch in the clone of `personal/angular` on your local computer.
|
|
You create the working branch from the up-to-date `main` branch of `personal/angular` on your local computer.
|
|
|
|
A working branch keeps your changes to the Angular documentation separate from the published documentation until it is ready.
|
|
A working branch also keeps your edits for one issue separate from those of another issue.
|
|
Finally, a working branch identifies the changes you made in the pull request that you submit when you're finished.
|
|
|
|
<div class="alert is-important">
|
|
|
|
**IMPORTANT**: <br />
|
|
Before you edit any Angular documentation, make sure that you are using the correct `working` branch.
|
|
You can confirm your current branch by running `git status` from your `working` directory before you start editing.
|
|
|
|
</div>
|
|
|
|
#### To create a `working` branch for editing
|
|
|
|
Perform these steps in a command-line program on your local computer.
|
|
|
|
1. [Update your fork of `angular/angular`](#update-your-fork-with-the-upstream-repo).
|
|
1. From your [workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer) directory, run this command to navigate to your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
|
|
Remember to replace `personal` with your GitHub username.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
cd personal/angular
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to check out the `main` branch.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
git checkout main
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to create your working branch.
|
|
Replace `working-branch` with the name of your working branch.
|
|
|
|
Name your working branch something that relates to your editing task, for example, if you are resolving `issue #12345`, you might name the branch, `issue-12345`.
|
|
If you are improving error messages, you might name it, `error-message-improvements`.
|
|
A branch name can have alphanumeric characters, hyphens, underscores, and slashes, but it can't have any spaces or other special characters.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
git checkout -b working-branch
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to make a copy of your working branch in your repo on `github.com` in the cloud.
|
|
Remember to replace `working-branch` with the name of your working branch.
|
|
|
|
<code-example format="shell" language="shell">
|
|
|
|
git push --set-upstream origin working-branch
|
|
|
|
</code-example>
|
|
|
|
## Edit the documentation
|
|
|
|
After you create a working branch, you're ready to start editing and creating topics.
|
|
|
|
<!-- links -->
|
|
|
|
<!-- external links -->
|
|
|
|
<!-- end links -->
|
|
|
|
@reviewed 2022-10-12
|