W3cubDocs

/Angular

Start to edit a documentation topic

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 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. Before you start editing a topic, update your clone of personal/angular.
A working branch that you create from an up-to-date main branch.

Creating your working branch is described later in this topic.

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.

IMPORTANT: Remember to replace personal with your GitHub username in the commands and examples in this topic.

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.

To update your fork and its clone with the upstream repo

Perform these steps from a command-line tool on your local computer.

From your workspace directory, run this command to navigate to your working directory. This step is not shown in the image. Remember to replace personal with your GitHub username.
```
cd personal/angular
```
Run this command to check out the main branch. This step is not shown in the image.
```
git checkout main
```
Run this command to update the main branch in the working directory on your local computer from the upstream angular/angular repo.
```
git fetch upstream
git merge upstream/main
```
Run this command to update your personal/angular repo on github.com with the latest from the upstream angular/angular repo.
```
git push
```

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.

IMPORTANT: 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.

To create a `working` branch for editing

Perform these steps in a command-line program on your local computer.

Update your fork of angular/angular.
From your workspace directory, run this command to navigate to your working directory. Remember to replace personal with your GitHub username.
```
cd personal/angular
```
Run this command to check out the main branch.
```
git checkout main
```
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.
```
git checkout -b working-branch
```
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.
```
git push --set-upstream origin working-branch
```

Edit the documentation

After you create a working branch, you're ready to start editing and creating topics.

Last reviewed on Wed Oct 12 2022