mirror of
https://github.com/angular/angular
synced 2026-05-24 09:28:37 +00:00
412 lines
15 KiB
Markdown
412 lines
15 KiB
Markdown
# Make and save changes to a documentation topic
|
|
|
|
<!-- markdownLint-disable MD001 -->
|
|
<!-- markdownLint-disable MD033 -->
|
|
|
|
This topic describes tasks that you perform while making changes to the documentation.
|
|
|
|
<div class="alert is-important">
|
|
|
|
**IMPORTANT**: <br />
|
|
Only perform these tasks after you have created a working branch in which to work as described in [Create a working branch for editing](guide/doc-update-start#create-a-working-branch-for-editing).
|
|
|
|
</div>
|
|
|
|
## Work in the correct working branch
|
|
|
|
Before you change any files, make sure that you are working in the correct working branch.
|
|
|
|
#### To set the correct working branch for editing
|
|
|
|
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).
|
|
Remember to replace `personal` with your GitHub username.
|
|
|
|
<code-example language="shell">
|
|
|
|
cd personal/angular
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to check out your working branch.
|
|
Replace `working-branch` with the name of the branch that you created for the documentation issue.
|
|
|
|
<code-example language="shell">
|
|
|
|
git checkout working-branch
|
|
|
|
</code-example>
|
|
|
|
## Edit the documentation
|
|
|
|
Review the [Angular documentation style guide](guide/styleguide) before you start editing to understand how to write and format the text in the documentation.
|
|
|
|
In your working branch, edit the files that need to be changed. Most documentation source files are found in the `aio/content/guide` directory of the `angular` repo.
|
|
|
|
Angular development tools can render the documentation as you make your changes.
|
|
|
|
#### To view the rendered documentation while you are editing
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = NO -->
|
|
|
|
Perform these steps from a command-line tool on your local computer or in the **terminal** pane of your IDE.
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = YES -->
|
|
|
|
1. Navigate to your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
|
|
1. From your working directory, run this command to navigate to the `aio` directory. The `aio` directory contains Angular's documentation files and tools.
|
|
|
|
<code-example language="shell">
|
|
|
|
cd aio
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to build the documentation locally.
|
|
|
|
<code-example language="shell">
|
|
|
|
yarn build
|
|
|
|
</code-example>
|
|
|
|
This builds the documentation from scratch, but does not serve it.
|
|
|
|
1. Run this command to serve and sync the documentation.
|
|
|
|
<code-example language="shell">
|
|
|
|
yarn start
|
|
|
|
</code-example>
|
|
|
|
This serves your draft of the angular.io website locally at `http://localhost:4200` and watches for changes to documentation files.
|
|
Each time you save an update to a documentation file, the angular.io website at `http://localhost:4200` is updated.
|
|
You might need to refresh your browser to see the changes after you save them.
|
|
|
|
### Documentation linting
|
|
|
|
If you installed Vale on your local computer and your IDE, each time you save a markdown file, Vale reviews it for common errors.
|
|
Vale, the documentation linter, reports the errors it finds in the **Problems** pane of Visual Studio Code.
|
|
The errors are also reflected in the documentation source code, as close to the problem as possible.
|
|
|
|
For more information about documentation linting and resolving lint problems, see [Resolve documentation linter messages](guide/docs-lint-errors).
|
|
|
|
## Save your changes
|
|
|
|
As you make changes to the documentation source files on your local computer, your changes can be in one of these states.
|
|
|
|
* **Made, but not saved**
|
|
|
|
This is the state of your changes as you edit a file in your integrated development environment (IDE).
|
|
|
|
* **Saved, but not committed**
|
|
|
|
After you save changes to a file from the IDE, they are saved to your local computer.
|
|
While the changes have been saved, they have not been recorded as a change by `git`, the version control software.
|
|
Your files are typically in this state as you review your work in progress.
|
|
|
|
* **Committed, but not pushed**
|
|
|
|
After you commit your changes to `git`, your changes are recorded as a *commit* on your local computer, but they are not saved in the cloud.
|
|
This is the state of your files when you've made some progress and you want to save that progress as a commit.
|
|
|
|
* **Committed and pushed**
|
|
|
|
After you push your commits to your personal repo in `github.com`, your changes are recorded by `git` and saved to the cloud.
|
|
They are not yet part of the `angular/angular` repo.
|
|
This is the state your files must be in before you can open a pull request for them to become part of the `angular/angular` repo.
|
|
|
|
* **Merged into Angular**
|
|
|
|
After your pull request is approved and merged, the changes you made are now part of the `angular/angular` repo and appear in the [angular.io](https://angular.io) web site.
|
|
Your documentation update is complete.
|
|
|
|
This section describes how to save the changes you make to files in your working directory.
|
|
If you are new to using `git` and GitHub, review this section carefully to understand how to save your changes as you make them.
|
|
|
|
### Save your changes to your local computer
|
|
|
|
How to save changes that you make to a file on your local computer is determined by your IDE.
|
|
Refer to your IDE for the specific procedure of saving changes.
|
|
This process makes your changes *saved, but not committed*.
|
|
|
|
### Review your rendered topics
|
|
|
|
After you save changes to a documentation topic, and before you commit those changes on your local computer, review the rendered topic in a browser.
|
|
|
|
#### To render your changes in a browser on your local computer
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = NO -->
|
|
|
|
Perform these steps from a command-line tool on your local computer or in the **terminal** pane of your IDE.
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = YES -->
|
|
|
|
1. From your [workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer) directory, run this command to navigate to the `aio` directory in your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
|
|
Remember to replace `personal` with your GitHub username.
|
|
|
|
<code-example language="shell">
|
|
|
|
cd personal/angular/aio
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to build the documentation using the files on your local computer.
|
|
|
|
<code-example language="shell">
|
|
|
|
yarn build
|
|
|
|
</code-example>
|
|
|
|
This command builds the documentation from scratch, but does not serve it for viewing.
|
|
|
|
1. Run this command to serve the documentation locally and rebuild it after it changes.
|
|
|
|
<code-example language="shell">
|
|
|
|
yarn start
|
|
|
|
</code-example>
|
|
|
|
This command serves the Angular documentation at [`http://localhost:4200`](http://localhost:4200).
|
|
You might need to refresh the browser after the documentation is updated to see the changes in your browser.
|
|
|
|
After you are satisfied with the changes, commit them on your local computer.
|
|
|
|
### Commit your changes on your local computer
|
|
|
|
Perform this procedure after you save the changes on your local computer and you are ready to commit changes on your local computer.
|
|
|
|
#### To commit your changes on your local computer
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = NO -->
|
|
|
|
Perform these steps from a command-line tool on your local computer or in the **terminal** pane of your IDE.
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = YES -->
|
|
|
|
1. From your [workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer) directory, run this command to navigate to the `aio` directory in your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
|
|
Remember to replace `personal` with your GitHub username.
|
|
|
|
<code-example language="shell">
|
|
|
|
cd personal/angular/aio
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to confirm that you are ready to commit your changes.
|
|
|
|
<code-example language="shell">
|
|
|
|
git status
|
|
|
|
</code-example>
|
|
|
|
The `git status` command returns an output like this.
|
|
|
|
<!-- Formatting this example as output hides the <file> text. -->
|
|
<code-example language="none" hideCopy>
|
|
|
|
On branch working-branch
|
|
Your branch is up to date with 'origin/working-branch
|
|
Changes not staged for commit:
|
|
(use "git add <file>..." to update what will be committed)
|
|
(use "git restore <file>..." to discard changes in working directory)
|
|
modified: content/guide/doc-build-test.md
|
|
modified: content/guide/doc-edit-finish.md
|
|
modified: content/guide/doc-editing.md
|
|
modified: content/guide/doc-pr-prep.md
|
|
modified: content/guide/doc-pr-update.md
|
|
modified: content/guide/doc-prepare-to-edit.md
|
|
modified: content/guide/doc-select-issue.md
|
|
modified: content/guide/doc-update-start.md
|
|
|
|
no changes added to commit (use "git add" and/or "git commit -a")
|
|
|
|
</code-example>
|
|
|
|
1. Confirm that you in the correct working branch.
|
|
|
|
If you are not in the correct branch, replace `working-branch` with the name of your working branch and then run `git checkout working-branch` to select the correct branch.
|
|
|
|
1. Review the modified files in the list.
|
|
Confirm that they are those that you have changed and saved, but not committed.
|
|
The list of modified files varies, depending on what you have edited.
|
|
|
|
1. Run this command to add a file that you want to commit.
|
|
Replace `filename` with a filename from the `git status` output.
|
|
|
|
<code-example language="shell">
|
|
|
|
git add filename
|
|
|
|
</code-example>
|
|
|
|
You can add multiple files in a single command by using wildcard characters in the filename parameter.
|
|
You can also run this command to add all changed files that are being tracked by `git` to the commit by using `*` filename as this example shows.
|
|
|
|
<code-example language="shell">
|
|
|
|
git add *
|
|
|
|
</code-example>
|
|
|
|
<div class="alert is-important">
|
|
|
|
**IMPORTANT**: <br />
|
|
Files that are not tracked by `git` are not committed or pushed to your repo on `github.com`, and they do not appear in your pull request.
|
|
|
|
</div>
|
|
|
|
1. Run `git status` again.
|
|
|
|
<code-example language="shell">
|
|
|
|
git status
|
|
|
|
</code-example>
|
|
|
|
1. Review the output and confirm the files that are ready to be committed.
|
|
|
|
<!-- Formatting this example as output hides the <file> text. -->
|
|
<code-example language="none" hideCopy>
|
|
|
|
On branch working-branch
|
|
Your branch is up to date with 'origin/working-branch'.
|
|
|
|
Changes to be committed:
|
|
(use "git restore --staged <file>..." to unstage)
|
|
modified: content/guide/doc-build-test.md
|
|
modified: content/guide/doc-edit-finish.md
|
|
modified: content/guide/doc-editing.md
|
|
modified: content/guide/doc-pr-prep.md
|
|
modified: content/guide/doc-pr-update.md
|
|
modified: content/guide/doc-prepare-to-edit.md
|
|
modified: content/guide/doc-select-issue.md
|
|
modified: content/guide/doc-update-start.md
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to commit the changed files to your local computer.
|
|
The commit message that follows the `-m` parameter must start with `docs:` followed by space, and your message.
|
|
Replace `detailed commit message` with a message that describes the changes you made.
|
|
|
|
<code-example language="shell">
|
|
|
|
git commit -m 'docs: detailed commit message'
|
|
|
|
</code-example>
|
|
|
|
For more information about Angular commit messages, see [Formatting commit messages for a pull request](guide/doc-pr-prep#format-commit-messages-for-a-pull-request).
|
|
|
|
Your changes to the documentation are now *committed, but not pushed*.
|
|
|
|
### Push your commits to the cloud
|
|
|
|
After you commit the changes to your local computer, this procedure pushes those commits to your `origin` repo in the cloud.
|
|
|
|
#### To push your changes to your origin repo in the cloud
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = NO -->
|
|
|
|
Perform these steps from a command-line tool on your local computer or in the **terminal** pane of your IDE.
|
|
|
|
<!-- vale Angular.Google_WordListSuggestions = YES -->
|
|
|
|
1. From your [workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer) directory, run this command to navigate to the `aio` directory in your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
|
|
Remember to replace `personal` with your GitHub username.
|
|
|
|
<code-example language="shell">
|
|
|
|
cd personal/angular/aio
|
|
|
|
</code-example>
|
|
|
|
1. Run this command to confirm that you are using the correct branch.
|
|
|
|
<code-example language="shell">
|
|
|
|
git status
|
|
|
|
</code-example>
|
|
|
|
If you aren't in the correct branch, replace `working-branch` with the name of your working branch and run `git checkout working-branch` to select the correct branch.
|
|
|
|
Git status also shows whether you have changes on your local computer that have not been pushed to the cloud.
|
|
|
|
<code-example language="none" hideCopy>
|
|
|
|
On branch working-branch
|
|
Your branch is ahead of 'origin/working-branch' by 1 commit.
|
|
(use "git push" to publish your local commits)
|
|
|
|
</code-example>
|
|
|
|
This example output says that there is one commit on the local computer that's not in the `working-branch` branch on the `origin` repo.
|
|
The `origin` is the `personal/angular` repo in GitHub.
|
|
The next command pushes that commit to the `origin` repo.
|
|
|
|
1. Run this command to push the commits on your local computer to your account on GitHub in the cloud.
|
|
|
|
<code-example language="shell">
|
|
|
|
git push
|
|
|
|
</code-example>
|
|
|
|
If this is the first time you've pushed commits from the branch, you can see a message such as this.
|
|
|
|
<code-example language="none" hideCopy>
|
|
|
|
fatal: The current branch working-branch has no upstream branch.
|
|
To push the current branch and set the remote as upstream, use
|
|
|
|
git push --set-upstream origin working-branch
|
|
|
|
To have this happen automatically for branches without a tracking
|
|
upstream, see 'push.autoSetupRemote' in 'git help config'.
|
|
|
|
</code-example>
|
|
|
|
If you get this message, copy the command that the message provides and run it as shown here:
|
|
|
|
<code-example language="shell">
|
|
|
|
git push --set-upstream origin working-branch
|
|
|
|
</code-example>
|
|
|
|
The changes that you made in the `working-branch` branch on your local computer have been saved on `github.com`.
|
|
Your changes to the documentation are now *committed and pushed*.
|
|
|
|
## Test your documentation
|
|
|
|
After you update the documentation to fix the issue that you picked, you are ready to test the documentation.
|
|
Testing documentation consists of:
|
|
|
|
* **Documentation linting**
|
|
|
|
Each time you open and save a documentation topic, the documentation linter checks for common errors.
|
|
For more information about documentation linting, see [Resolving documentation linter messages](guide/docs-lint-errors).
|
|
|
|
* **Manual review**
|
|
|
|
When your documentation update is complete, have another person review your changes.
|
|
If you have updated technical content, have a subject matter expert on the topic review your update, as well.
|
|
|
|
* **Automated testing**
|
|
|
|
The Angular documentation is tested automatically after you open a pull request.
|
|
It must pass this testing before the pull request can be merged.
|
|
For more information about automated documentation testing, see [Testing a documentation update](/guide/doc-build-test).
|
|
|
|
<!-- links -->
|
|
|
|
<!-- external links -->
|
|
|
|
<!-- end links -->
|
|
|
|
@reviewed 2022-10-12
|