Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: update of documentation contrib. guide (#47381)

Browse source 
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
This commit is contained in:
Bob Watson 2022-08-17 15:44:54 -07:00 committed by Jessica Janiuk
parent ec97331c8e
commit 6c98ca4572
57 changed files with 3101 additions and 292 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
.pullapprove.yml
View file

@ -1083,6 +1083,28 @@ groups:
'aio/content/guide/reviewing-content.md',
'aio/content/guide/updating-content-github-ui.md',
'aio/content/guide/updating-search-keywords.md',
'aio/content/guide/doc-build-test.md',
'aio/content/guide/doc-edit-finish.md',
'aio/content/guide/doc-editing.md',
'aio/content/guide/doc-github-tasks.md',
'aio/content/guide/doc-pr-open.md',
'aio/content/guide/doc-pr-prep.md',
'aio/content/guide/doc-pr-update.md',
'aio/content/guide/doc-prepare-to-edit.md',
'aio/content/guide/doc-select-issue.md',
'aio/content/guide/doc-tasks.md',
'aio/content/guide/doc-update-overview.md',
'aio/content/guide/doc-update-start.md',
'aio/content/guide/docs-lint-errors.md',
'aio/content/images/guide/preparing-to-edit-docs/**/{*,.*}',
'aio/content/images/guide/github-for-docs/**/{*,.*}',
'aio/content/images/guide/doc-update-start/**/{*,.*}',
'aio/content/images/guide/doc-update-overview/**/{*,.*}',
'aio/content/images/guide/doc-pr-update/**/{*,.*}',
'aio/content/images/guide/doc-pr-prep/**/{*,.*}',
'aio/content/images/guide/doc-pr-open/**/{*,.*}',
'aio/content/images/guide/doc-github-tasks/**/{*,.*}',
'aio/content/images/guide/doc-prepare-to-edit/**/{*,.*}',
])
reviewers:
users:

179
aio/content/guide/contributors-guide-overview.md
View file

@ -1,135 +1,134 @@
# Documentation contributor guide
# Documentation contributors guide
<!-- markdownLint-disable MD001 -->
The topics in this section describe how you can contribute to this documentation.
For information about contributing only code to the Angular framework, see [Contributing to Angular][GithubAngularAngularBlobMainContributingMd].
For information about contributing code to the Angular framework, see [Contributing to Angular][GithubAngularAngularBlobMainContributingMd].
Angular, an open source project, depends on its community, especially when it comes to the documentation.
The more the community contributes to the documentation, the better the documentation becomes.
Input from you helps both new and experienced Angular developers.
Angular is an open source project that appreciates its community support, especially when it comes to the documentation.
You can update the Angular documentation in these ways:
* [Make a minor change][AioGuideContributorsGuideOverviewMakeAMinorChange]
* [Make a major change][AioGuideContributorsGuideOverviewMakeAMajorChange]
<div class="alert is-important">
You must have a GitHub account to propose a minor change or review and edit the documentation.
**IMPORTANT**:<br />
To submit changes to the Angular documentation, you must have:
* A [GitHub][GithubMain] account
* A signed [Contributor License Agreement][GithubAngularAngularBlobMainContributingMdSigningTheCla]
</div>
## Propose a minor change
## Make a minor change
You can propose minor changes to a documentation topic without downloading any software. Choose the pencil icon&nbsp;<img alt="drawing of a pencil used as the topic edit icon" src="generated/images/guide/contributors-guide/edit-icon.png" > at the top of the page, to the right of the topic title to enter your suggestion.
You can make minor changes to a documentation topic without downloading any software.
Many common documentation maintenance tasks require only minor changes to a few words or characters in a topic.
Examples of minor changes include:
## Review and edit documentation topics
* [Correcting a typo or two][AioGuideContributorGuideOverviewToMakeAMinorChangeToADocumentationTopic]
* [Reviewing a topic and updating its review date][AioGuideReviewingContentUpdateTheLastReviewedDate]
* [Adding or updating search keywords][AioGuideUpdatingSearchKeywords]
This section describes how to make larger contributions to the documentation.
For more about keeping the documentation up to date, see [Common documentation maintenance tasks][AioGuideDocTasks].
### Before you start
To make larger changes to the documentation, you must install an Angular development environment on your local computer.
You need this environment to edit and test your changes before you submit them.
For information about configuring your local computer to make larger documentation updates, see [Preparing to edit the documentation][AioGuideDocPrepareToEdit].
The following steps set up your local computer to contribute documentation content.
<!-- markdownLint-disable MD033 -->
1. Sign in to your account on GitHub.
If you don't have an account on GitHub, [create a new account][GithubJoin] before you continue.
2. In your browser, navigate to [https://github.com/angular/angular][GithubAngular].
3. In your browser, fork the `angular/angular` repo into your GitHub account.
1. From [https://github.com/angular/angular][GithubAngular] in the browser, choose the **Fork** button near the top-right corner of the page.
2. If asked, choose to create a fork to contribute to the original project.
4. On the computer that you want to edit, clone your fork of the `angular` repo.
5. In the `angular/aio` directory of your cloned repo, locally build and view the documentation.
1. Run the following commands.
To learn more, see [Angular documentation project][GithubAngularAngularBlobMainAioReadmeMd].
#### To make a minor change to a documentation topic
<code-example format="shell" language="shell">
Perform these steps in a browser.
yarn
1. Confirm you have a [signed Contributor License Agreement (CLA)][GoogleDeveloperClaClas] on file.
If you don't, [sign a CLA][GithubAngularAngularBlobMainContributingMdSigningTheCla].
</code-example>
1. Sign into [github.com][GithubMain], or if you don't have a GitHub account, [create a new GitHub account][GithubJoin].
1. Navigate to the page in [angular.io][AngularMain] that you want to update.
1. On the page that you want to update, locate this pencil icon to the right of the topic's title
<code-example format="shell" language="shell">
<div class="lightbox">
yarn setup
<img alt="drawing of a pencil used as the topic edit icon" src="generated/images/guide/contributors-guide/edit-icon.png">
</code-example>
</div>
<code-example format="shell" language="shell">
1. Click this icon to open the suggestion page.
1. In the suggestion page, in **Edit file**, update the content to fix the problem.
If the fix requires more than correcting a few characters, it might be better to treat this as a [major change][AioGuideContributorsGuideOverviewMakeAMajorChange].
yarn build
1. Click the **Preview** tab to see how your markdown changes look when rendered.
This view shows how the markdown renders.
It won't look exactly like the documentation page because it doesn't display the text with the styles used in the documentation.
</code-example>
1. After you finish making your changes:
1. In **Propose changes**, enter a brief description of your changes that starts with `docs:` and is 100 characters or less in length.
If necessary, you can add more information about the change in the larger edit window below the brief description.
<code-example format="shell" language="shell">
1. Select **Create a new branch for this commit and start a pull request** and accept the default branch name.
1. Click **Propose changes** to open a pull request with your updated text.
yarn start
After you open a pull request, the Angular team reviews your change and merges it into the documentation.
You can follow the progress of your pull request in the pull request's page.
You might receive a notification from GitHub if the Angular team has any questions about your change.
</code-example>
## Make a major change
<div class="callout is-helpful">
Making major changes or adding new topics to the documentation follows a different workflow.
Major changes to a topic require that you build and test your changes before you send them to the Angular team.
**NOTE**: <br/>
If you have any errors or issues with your yarn install, just re-run the `yarn` command.
These topics provide information about how to set up your local computer to edit, build, and test Angular documentation to make major changes to it.
</div>
* [Overview of the Angular documentation editorial workflow][AioGuideDocUpdateOverview]
2. In your browser, navigate to [http://localhost:4200][AngularLocalhost]
3. Review your local build of the Angular framework documentation.
Describes how to configure your local computer to build, edit, and test Angular documentation
After you can see your local build of the Angular framework documentation on your own system, you are ready to review and edit it. The following sections help you with the next steps.
* [Documentation style guide][AioGuideDocStyleGuide]
### Before you edit the documentation
Describes the standards used in the Angular documentation
The following steps prepare you to edit the Angular documentation successfully:
## Localize Angular documentation in a new language
1. Review [Contributing to Angular][GithubAngularAngularBlobMainContributingMd].
2. Install [the documentation linter][GithubAngularAngularTreeMainAioToolsDocLinterInstallValeOnYourDevelopmentSystemReadmeMd].
### Ways to contribute to Angular documentation
<div class="card-container">
<a href="guide/reviewing-content" class="docs-card" title="Reviewing content">
<section>Review content</section>
<p>Keep Angular content up-to-date by reviewing topics for accuracy.</p>
<p class="card-footer">Help keep content up to date</p>
</a>
<a href="guide/updating-search-keywords" class="docs-card" title="Updating search keywords">
<section>Update search keywords</section>
<p>Help Angular developers by improving the search keywords for existing topics.</p>
<p class="card-footer">Improve documentation search</p>
</a>
<a href="guide/updating-content-github-ui" class="docs-card" title="Updating content through GitHub">
<section>Update content through GitHub</section>
<p>Learn how to make documentation changes through the GitHub UI.</p>
<p class="card-footer">Contribute to Angular in your browser</p>
</a>
</div>
### More resources for contributing to documentation
<div class="card-container">
<a href="guide/docs-style-guide" class="docs-card" title="Documentation Style Guide">
<section>Documentation style guide</section>
<p>Review the syntax and styles used within the Angular documentation set.</p>
<p class="card-footer">Get to know the writing style</p>
</a>
<a href="guide/localizing-angular" class="docs-card" title="Angular localization guidelines">
<section>Angular localization guidelines</section>
<p>Learn about the guidelines for localizing Angular documentation.</p>
<p class="card-footer">Localize documentation</p>
</a>
</div>
Localizing Angular documentation is another way to contribute to Angular documentation.
For information about localizing the Angular documentation in a new language, see [Angular localization guidelines][AioGuideLocalizingAngular].
<!-- links -->
[AioGuideContributorsGuideOverviewMakeAMajorChange]: guide/contributors-guide-overview#make-a-major-change "Make a major change - Documentation contributors guide | Angular"
[AioGuideContributorsGuideOverviewMakeAMinorChange]: guide/contributors-guide-overview#make-a-minor-change "Make a minor change - Documentation contributors guide | Angular"
[AioGuideContributorGuideOverviewToMakeAMinorChangeToADocumentationTopic]: guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic "To make a minor change to a documentation topic - Documentation contributors guide | Angular"
[AioGuideDocPrepareToEdit]: guide/doc-prepare-to-edit "Preparing to edit documentation | Angular"
[AioGuideDocStyleGuide]: guide/docs-style-guide "Angular documentation style guide | Angular"
[AioGuideDocTasks]: guide/doc-tasks "Common documentation maintenance tasks | Angular"
[AioGuideDocUpdateOverview]: guide/doc-update-overview "Overview of Angular documentation editing | Angular"
[AioGuideLocalizingAngular]: guide/localizing-angular "Angular documentation style guide | Angular"
[AioGuideReviewingContentUpdateTheLastReviewedDate]: guide/reviewing-content#update-the-last-reviewed-date "Update the last reviewed date - Test a documentation update | Angular"
[AioGuideUpdatingSearchKeywords]: guide/updating-search-keywords "Updating search keywords | Angular"
<!-- external links -->
[AngularMain]: https://angular.io "Angular"
[GithubAngularAngularBlobMainContributingMd]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md "Contributing to Angular | angular/angular | GitHub"
[GithubAngularAngularBlobMainContributingMdSigningTheCla]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-signing-the-cla "Signing the CLA - Contributing to Angular | angular/angular | GitHub"
[GithubMain]: https://github.com "GitHub"
[GithubJoin]: https://github.com/join "Join GitHub | GitHub"
[GithubAngular]: https://github.com/angular/angular "angular/angular | GitHub"
[GithubAngularAngularBlobMainAioReadmeMd]: https://github.com/angular/angular/blob/main/aio/README.md "Angular documentation project (https://angular.io) | angular/angular | Github"
[GithubAngularAngularBlobMainContributingMd]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md "Contributing to Angular | angular/angular | Github"
[GithubAngularAngularTreeMainAioToolsDocLinterInstallValeOnYourDevelopmentSystemReadmeMd]: https://github.com/angular/angular/tree/main/aio/tools/doc-linter/README.md#install-vale-on-your-development-system "Install Vale on your development system - Angular documentation lint tool | angular/angular | Github"
[AngularLocalhost]: http://localhost:4200 "Angular.io on localhost"
[GoogleDeveloperClaClas]: https://cla.developers.google.com/clas "Contributor License Agreements | Google Open Source"
<!--end links -->
@reviewed 2022-08-08
@reviewed 2022-10-12

103
aio/content/guide/doc-build-test.md Normal file
View file

@ -0,0 +1,103 @@
# Build and test a documentation update
<!-- markdownLint-disable MD001 -->
<!-- markdownLint-disable MD033 -->
After you have completed your documentation update, you want to run the documentation's end-to-end tests on your local computer. These tests are some of the tests that are run after you open a pull request. You can find end-to-end test failures faster when you run them on your local computer than after you open a pull request.
## Build the documentation on your local computer
Before you test your updated documentation, you want to build it to make sure you test your latest changes.
#### To build the documentation 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. Navigate to your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
2. 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>
3. Run this command to build the documentation locally.
<code-example language="shell">
yarn build
</code-example>
This builds the documentation from scratch.
After you build the documentation on your local computer, you can run the angular.io end-to-end test.
## Run the angular.io end-to-end test on your local computer
This procedure runs most, but not all, of the tests that are run after you open a pull request.
#### To run the angular.io end-to-end test on your local computer
On your local computer, in a command line tool or the **Terminal** pane of your IDE:
1. Run this command from your [workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer) directory to navigate to your [working directory](guide/doc-prepare-to-edit#doc-working-directory).
<code-example format="shell" language="shell">
cd personal/angular
</code-example>
1. Replace `working-branch` with the name of your `working` branch and run this command to check out your `working` branch.
<code-example format="shell" language="shell">
git checkout working-branch
</code-example>
1. Run this command to navigate to the documentation.
<code-example format="shell" language="shell">
cd aio
</code-example>
1. Run this command to start the end-to-end tests.
<code-example format="shell" language="shell">
yarn e2e
</code-example>
1. Watch for errors that the test might report.
## No errors reported
If the end-to-end tests report no errors and your update has passed [all other reviews](guide/doc-editing#test-your-documentation) required,
your documentation update is ready for a pull request.
After you open your pull request, GitHub tests the code in your pull request.
The tests that GitHub runs include the end-to-end tests that you just ran and other tests that only run in the GitHub repo.
Because of that, even though your update passed the end-to-end tests locally, your update could still report an error after you open a pull request.
## Errors reported
If the end-to-end tests report an error on your local computer, be sure to correct it before you open a pull request.
If the update fails the end-to-end test locally, it is likely to also fail the tests that run after you open a pull request.
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

143
aio/content/guide/doc-edit-finish.md Normal file
View file

@ -0,0 +1,143 @@
# Finish up a documentation pull request
<!-- markdownLint-disable MD001 -->
This topic describes how to keep your workspace tidy after your pull request is merged and closed.
## Review the commit log of the upstream repo
This procedure confirms that your commit is now in the `main` branch of the `angular/angular` repo.
#### To review the commit log on <code>github.com</code> for your commit
In a web browser, open [`https://https://github.com/angular/angular/commits/main`](https://github.com/angular/angular/commits/main).
1. Review the commit list.
1. Find the entry with your GitHub username, commit message, and pull request number of your commit.
The commit number might not match the commit from your working branch because of how commits are merged.
1. If you see your commit listed, your commit has been merged into `angular/angular` and you can continue cleaning up your workspace.
1. If you don't see your commit in the list, you might need to wait before you retry this step.
Do not continue cleaning your workspace until you see your commit listed in or after the log entry that contains `origin/main`.
1. If you see your commit listed above the log entry that contains `origin/main`, then you might need to update your clone of the `angular/angular` repo again.
## Update your fork from the upstream repo
After you see that the commit from your pull request has been merged into the upstream `angular/angular` repo, update your fork.
This procedure updates your clone of `personal/angular` on your local computer and then, the repo in the cloud.
#### To update your fork 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).
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 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>
1. Run this command to review the commit log of your fork.
The `main` branch on your local computer and your origin repo on `github.com` are now in sync with the upstream `angular/angular` repo.
Run this command to list the recent commits.
<code-example format="shell" language="shell">
git log --pretty=format:"%h %as %an %Cblue%s %Cgreen%D"
</code-example>
1. In the output of the previous `git log` command, find the entry with your GitHub username, commit message, and pull request number of your commit.
The commit number might not match the commit from your working branch because of how commits are merged.
You should find the commit from your pull request in or near the log entry that contains `upstream/main`.
If you find the commit from your pull request in the correct place, you can continue to delete your working branch.
## Delete the working branch
After you confirm that your pull request is merged into `angular/angular` and appears in the `main` branch of your fork, you can delete the `working` branch.
Because your working branch was merged into the `main` branch of your fork, and the pull request has been closed, you no longer need the `working` branch.
It might be tempting to keep it around, just in case, but it is probably not necessary.
If you keep all your old working branches, your repository can collect unnecessary clutter.
#### To delete your working branch
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 delete the working branch used in the pull request from your local computer.
Replace `working-branch-name` with the name of your working branch.
<code-example format="shell" language="shell">
git branch -d working-branch-name
</code-example>
1. Run this command to delete the working branch from your `personal/angular` repo on `github.com`.
Replace `working-branch-name` with the name of your working branch.
<code-example format="shell" language="shell">
git push -d origin working-branch-name
</code-example>
## Next step
After you delete the working branch for your last issue, you're ready to [select another issue to resolve](guide/doc-select-issue).
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

412
aio/content/guide/doc-editing.md Normal file
View file

@ -0,0 +1,412 @@
# 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 serve-and-sync
</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 serve-and-sync
</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 &lt;file&gt;..." to update what will be committed)
(use "git restore &lt;file&gt;..." 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 &lt;file&gt;..." 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

498
aio/content/guide/doc-github-tasks.md Normal file
View file

@ -0,0 +1,498 @@
# Common GitHub tasks to edit angular.io
<!-- markdownLint-disable MD001 -->
<!-- markdownLint-disable MD033 -->
These are some of the common `git` tasks that you perform while editing Angular documentation.
The procedures in this topic assume that the files on your local computer are organized as illustrated in the following diagram.
<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-github-tasks/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 assume that your working directories are in a single `workspace` directory such that
* The local `working` directory of the upstream repo, `angular/angular` is in the `angular` subdirectory of the `angular` subdirectory of the `workspace` directory
* The local `working` directory of the origin repo, `personal/angular` is in the `angular` subdirectory of the `personal` subdirectory of the `workspace` directory
* The procedures assume that you are starting from your `workspace` directory
## Update your clone of the upstream repo
The upstream repo is the `angular/angular` repo.
As it is updated, such as by merging pull requests, your clone falls behind.
To keep your clone of `angular/angular` up-to-date, you want to follow this procedure daily.
This procedure updates your **clone** of the `angular/angular` repo on your local computer so it has the current code, as illustrated here.
The circled number correspond to the procedure step.
<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 pull process used to update the local computer" src="generated/images/guide/doc-github-tasks/github-sync-upstream.png">
</div>
#### To update your clone of the upstream repo
1. From your `workspace` directory, navigate to the `working` directory of the upstream repo.
<code-example format="shell" language="shell">
cd angular/angular
</code-example>
1. Check out the `main` branch.
<code-example format="shell" language="shell">
git checkout main
</code-example>
1. Update the `main` branch in the `working` directory on your local computer with any changes in the upstream `angular/angular` repo.
<code-example format="shell" language="shell">
git pull
</code-example>
The `main` branch of the clone on your local computer and the upstream repo on `github.com` are now in sync.
Now would be a good time to update your fork as well.
## Update your fork with the upstream repo
You want to sync the `main` branch of your fork with the `main` branch of the upstream, `angular/angular` repo at least daily.
This is good thing to do at the beginning of each day.
Sync your fork after you update your clone of the upstream repo and before you start working on the Angular documentation.
This procedure updates your **fork** of the `angular/angular` repo on your local computer so it has the current code, 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-github-tasks/github-fetch-merge.png">
</div>
#### To update your fork with the upstream repo
1. From your workspace directory, navigate to your working directory.
<code-example format="shell" language="shell">
cd personal/angular
</code-example>
1. Check out the `main` branch.
<code-example format="shell" language="shell">
git checkout main
</code-example>
1. 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. 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 and your *origin* repo on `github.com` are now in sync.
They have been updated with any changes to the upstream `angular/angular` repo that were made since the last time you updated your fork.
## Create a working branch for editing
Almost all your editing on the Angular documentation is done:
* In the clone of your fork of `angular/angular`, not in your clone of `angular/angular`
* In a `working` or `feature` branch made from the `main` branch
If this isn't clear, see [More about branches](#more-about-branches).
Before you start editing the Angular documentation, you want to:
1. [Update your clone of `angular/angular`](#update-your-clone-of-the-upstream-repo).
1. [Update your fork of `angular/angular`](#update-your-fork-with-the-upstream-repo).
1. Create a working branch from the `main` branch.
A working branch gives you a way to keep track of the changes that you make to the Angular documentation.
You also need a separate branch to submit those changes in a pull request.
Creating a working branch also keeps your changes for one update separate from those of another.
<div class="alert is-informational">
**NOTE**: <br />
Before you edit 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
1. [Update your clone of `angular/angular`](#update-your-clone-of-the-upstream-repo).
1. [Update your fork of `angular/angular`](#update-your-fork-with-the-upstream-repo).
1. From your `workspace` directory, navigate to your `working` directory.
<code-example format="shell" language="shell">
cd personal/angular
</code-example>
1. Check out the `main` branch.
<code-example format="shell" language="shell">
git checkout main
</code-example>
1. Create your new branch.
Replace `new-branch` with the name of your new branch.
Name the 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 new-branch
</code-example>
1. Push the new branch to your repo on `github.com` so you have a copy of it in the cloud.
Remember to replace `new-branch` with the name of your new branch.
<code-example format="shell" language="shell">
git push --set-upstream origin new-branch
</code-example>
## Save your changes
This section describes how to save the changes you make to files in the working directory of your fork of the Angular repo.
If you are new to using git and GitHub, review this section carefully to understand how to save your changes as you make them.
As you make changes to files in the working directory of your fork of the Angular repo, your changes can be:
* **Made but not saved**
This is the state of your changes as you edit a file in your integrated development environment \(IDE\).
This is the state of your changes as you're making them in your 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 reached a milestone and save your progress locally.
* **Committed and pushed**
After you push your commits to your personal repo in `github.com`, your changes have been recorded by `git` and saved to the cloud. They are not yet part of the `angular/angular` repo.
This is the state your files need to be in before you can open a pull request for it 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.
### Save your changes to your local computer
How to save changes to a file on your local computer is determined by your IDE.
Refer to your IDE for the specific procedure of saving changes.
### Commit your changes on your local computer
Follow this procedure after you save changes on your local computer and you are ready to commit changes to `git` on your local computer.
#### To commit your changes on your local computer
1. From your workspace directory, navigate to your working directory.
<code-example format="shell" language="shell">
cd personal/angular
</code-example>
1. Confirm you are using the correct branch.
If you aren't in the correct branch, run `git checkout branch-name` to select the correct branch.
<code-example format="shell" language="shell">
git status
</code-example>
1. Review the list of files to add to the commit is correct.
<code-example format="shell" language="shell">
git status
</code-example>
1. Add the files you want to commit.
<code-example format="shell" 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 add all changed files that are already being tracked by `git` to the commit by using `--all` option as this example shows.
<code-example format="shell" language="shell">
git add --all
</code-example>
1. Commit the changes to the local computer.
Replace `detailed-commit-comment` with a specific comment that describes the changes you made.
<code-example format="shell" language="shell">
git commit -m 'docs: detailed-commit-comment'
</code-example>
### Push your changes to your GitHub account in the cloud
After you have committed changes to your local computer, this procedure saves your commits to your GitHub account in the cloud.
#### To push your changes to your GitHub account in the cloud
1. From your `workspace` directory, navigate to your `working` directory.
<code-example format="shell" language="shell">
cd personal/angular
</code-example>
1. Confirm you are using the correct branch.
If you aren't in the correct branch, run `git checkout branch-name` to select the correct branch.
<code-example format="shell" language="shell">
git status
</code-example>
1. Push the commits on your local computer to your account on GitHub in the cloud.
<code-example format="shell" 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 format="shell" language="shell">
fatal: The current branch my-new-branch has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin my-new-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 format="shell" language="shell">
git push --set-upstream origin my-new-branch
</code-example>
### Open pull requests to merge a change into `angular/angular`
For information about preparing your changes to open a pull request, see [Preparing documentation for a pull request](guide/doc-pr-prep).
## Keep your branch up-to-date
If your changes to the documentation take more than a day, the `angular/angular` repo can change while you're editing.
Before you can merge your changes, they must be made on top of the current code.
You must update your working branch after you've made all your changes and before you open a pull request.
You might also want to keep your working branch updated as you're editing.
Either way, the procedure to update your branch is the same.
#### To keep your branch up-to-date
1. [Update your clone of `angular/angular`](#update-your-clone-of-the-upstream-repo).
1. [Update your fork of `angular/angular`](#update-your-fork-with-the-upstream-repo).
1. From your workspace directory, navigate to your working directory.
<code-example format="shell" language="shell">
cd personal/angular
</code-example>
1. Confirm that you are using the correct branch.
If you aren't in the correct branch, run `git checkout branch-name` to select the correct branch.
<code-example format="shell" language="shell">
git status
</code-example>
If you have any un-commited changes, [Commit your changes on your local computer](#commit-your-changes-on-your-local-computer) before you continue.
1. Rebase your branch to add the changes in your branch to the current content in the `main` branch.
<code-example format="shell" language="shell">
git rebase main
</code-example>
1. Update the branch in your repo in the cloud.
<code-example format="shell" language="shell">
git push --force-with-lease
</code-example>
## More about branches
`git` is a version control system that tracks the changes made to the files in a repo.
It does this by maintaining a lists of changes called `commits`.
A commit is a list of all the things that changed in a repo since the last commit.
### What are branches
A `branch` is a list of commits.
The `main` branch is the list of commits that reflects the current state of the project.
When a repo is created, the first commit is usually to the `main` branch and contains the files used in the creation of the repo.
The change list in that commit contains the names and the contents of the files that were added to create the repo.
The next time files in the repo are added or changed, another commit is created to describe what has changed.
After a five commits, the `main` branch can be imagined as the following diagram.
The diagram shows a series of changes that are recorded as commits, each represented as a circle and identified by a unique number.
<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="A row of circles, each numbered 1 through 5 and connected by a horizontal line" src="generated/images/guide/doc-github-tasks/main-branch.png">
</div>
In this example, the result of all the changes in commits one through five is the current state of the repo.
### Creating a working branch
In `angular/angular`, the `main` branch contains all the changes that have been made to the Angular project since it began to get it to where it is today.
The list of commits in the `main` branch have all been reviewed and tested.
When you update the documentation, you might need to make several changes before have exactly what you want.
You don't want to open a pull request to merge your changes into `main` until you have had a chance to test and review them.
To do this you create a new `working` branch in which to work.
This example names the new `working` branch.
<code-example format="shell" language="shell">
&num; From the working directory of your personal/angular repo
git checkout main; &num; start from the main branch
git checkout -b working; &num; create a new branch named "working"
</code-example>
The `working` branch starts with all the changes that have already been made in the `main` branch.
From this, you can make your own changes.
After making two commits in the `working` branch, the branches in the repo can be imagined as this illustration.
<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="A row of circles, each numbered 3 through 5 connected by a horizontal line with a line coming vertically out of circle 5 to create a branch" src="generated/images/guide/doc-github-tasks/feature-with-new-branch.png">
</div>
### Merging your work into the main branch
If the changes you made in the two commits from the previous section have what you want to use.
That is, you have reviewed and tested those changes.
You can open a pull request to merge those new changes into the `main` branch.
If no changes have been made to the `main` branch since you created your branch, the merge is called `fast-forwarding`.
In a `fast-forward` merge the two commits you added to the `working` branch are added to the `main` branch.
<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="A row of circles, each numbered 3 through 7 connected by a horizontal line with a line coming vertically out of circle 5 to create a branch" src="generated/images/guide/doc-github-tasks/feature-branch-ff.png">
</div>
After the `working` branch has been merged with the `main` branch, the `main` branch now includes the two commits you made in the `working` branch.
Because both branches include commits 1-7, they now have the same content.
### Merging your work into a changed main branch
Being able to `fast-foward` a merge is simple.
Unfortunately, in a repo like `angular/angular` that has many contributors, the main branch is changing frequently.
A more likely scenario is illustrated here, where the `main` branch changed while you're working on your changes in the `working` branch.
The resulting branches could be imagined as the following illustration.
While you were working on commits six and seven, others had contributed commits eight and nine.
<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="A row of circles, each numbered 3 through 9 connected by a horizontal line with a line coming vertically out of circle 5 to create a branch" src="generated/images/guide/doc-github-tasks/feature-branch-w-update.png">
</div>
The commits six and seven can't be used to fast-forward.
Remember that a commit is a list of changes.
Commit six is the list of changes from commit five plus the first edit you made.
Commit seven is the list of changes from your commit six plus the changes you made in response to your review comments.
In any case, the commits from your `working` branch can't be added to the commit nine in the main branch.
The commits from the `working` branch don't include the changes from commits eight and nine, so they could be lost.
You cam choose to merge the changes in the two branches or to rebase the commits in your `working` branch.
Merging creates a `merge` commit to reconcile the changes necessary to represent the net result of both branches.
While merging isn't bad, it makes it hard to undo the individual changes.
@reviewed 2022-09-30

130
aio/content/guide/doc-pr-open.md Normal file
View file

@ -0,0 +1,130 @@
# Open a documentation pull request
This topic describes how to open the pull request that requests your documentation update to be added to the `angular/angular` repo.
These steps are performed in your web browser.
1. Locate the `working` branch that you want to use for your pull request.
In this example, `test-1` is the name of the `working` branch.
Choose one of these options to open a pull request.
1. If you recently pushed the branch that you want to use to the `origin` repo, you might see it listed on the code page of the `angular` repo in your GitHub account.
This image shows an example of a repo that has had several recent updates.
<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="Screenshot of github.com page showing a recent push to the repo" src="generated/images/guide/doc-pr-open/github-recent-push.png">
</div>
In the alert message with your `working` branch, click **Compare &amp; pull request** to open a pull request and continue to the next step.
1. You can also select your `working` branch in the code page of the origin repo.
<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="Screenshot of code page of the origin repo from github.com page showing a branch listing from a repo" src="generated/images/guide/doc-pr-open/github-branch-view.png">
</div>
Click the link text in the `"This branch is"` message to open the **Comparing changes** page.
<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="Screenshot of Comparing Changes page in github.com page showing a difference between branches of a repo" src="generated/images/guide/doc-pr-open/github-branch-diff.png">
</div>
In the **Comparing changes** page, click **Create pull request** to open the new pull request page.
1. Review and complete the form in the comment field.
Most documentation updates require responses to the entries noted by an arrow and described below.
<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="Screenshot of pull request form" src="generated/images/guide/doc-pr-open/pr-checklist.png">
</div>
<!-- vale Angular.Google_We = NO -->
1. **The commit message follows our guidelines**
Mark this comment when you're sure your commit messages are in the correct format.
Remember that the commit messages and the pull request title are different.
For more information about commit message formatting, see [Preparing a documentation update for a pull request](guide/doc-pr-prep) and [Commit message format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit).
1. **Docs have been added / updated \(for bug fixes / features\)**
Mark this comment to show that documentation has been updated.
1. **Documentation content changes**
Mark this comment to identify this is a documentation pull request.
If you also updated other types of content, you can mark those as well.
1. **What is the current behavior?**
Briefly describe what wasn't working or what was incorrect in the documentation before you made the changes in this pull request.
Add the issue number here, if the problem is described in an issue.
1. **What is the new behavior?**
Briefly describe what was added to fix the problem.
1. **Does this PR introduce a breaking change?**
For most documentation updates, the answer to this should be `No`.
1. **Other information**
Add any other information that can help reviewers understand your pull request here.
<!-- vale Angular.Google_We = YES -->
1. Click the arrow next to **Draft pull request** and select whether you want to create a draft pull request or a pull request.
1. A draft pull request runs the continuous integration \(CI\) testing, but does not send the pull request to reviewers.
You can ask people to review it by sending them the pull request link.
You might use this option to see how your pull request passes the CI testing before you send it for review to be merged.
Draft pull requests cannot be merged.
1. A pull request runs the continuous integration \(CI\) testing and sends your pull request to reviewers to review and merge.
<div class="alert is-helpful">
**NOTE**: <br />
You can change draft pull requests to pull requests.
</div>
1. Click **Create the pull request** or **Draft pull request** to open the pull request.
After GitHub creates the pull request, the browser opens the new pull request page.
1. After you open the pull request, the automated tests start running.
## What happens after you open a pull request
In most cases, documentation pull requests that pass the automated tests are approved within a few days.
Sometimes, reviewers suggest changes for you to make to improve your pull request.
In those case, review the suggestions and [update the pull request](guide/doc-pr-update) with a comment or an updated file.
### What happens to abandoned pull requests
While it can take a few days to respond to comments, try to respond as quickly as you can.
Pull requests that appear to abandoned or ignored are closed according to this schedule:
* After 14 days of inactivity after the last comment, the author is reminded that the pull request has pending comments
* After 28 days of inactivity after the last comment, the pull request is closed and not merged
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

361
aio/content/guide/doc-pr-prep.md Normal file
View file

@ -0,0 +1,361 @@
# Prepare a documentation update for a pull request
This topic describes how to prepare your update to the Angular documentation so that you can open a pull request.
A pull request is how you share your update in a way that allows it to be merged it into the `angular/angular` repo.
<div class="alert is-important">
**IMPORTANT**: <br />
Make sure that you have reviewed your documentation update, removed any lint errors, and confirmed that it passes the end-to-end \(e2e\) tests without errors.
</div>
A pull request shares a branch in `personal/angular`, your forked repo, with the `angular/angular` repo.
After your pull request is approved and merged, the new commits from your branch are added to the main branch in the `angular/angular` repo.
The commits in your branch, and their messages, become part of the `angular/angular` repo.
What does this mean for your pull request?
1. Your commit messages become part of the documentation of the changes made to Angular.
Because they become part of the `angular/angular` repo, they must conform to a specific format so that they are easy to read.
If they aren't correctly formatted, you can fix that before you open your pull request.
1. You might need to squash the commits that you made while developing your update.
It's normal to save your changes as intermediate commits while you're developing a large update, but your pull request represents only one change to the `angular/angular` repo.
Squashing the commits from your working branch into fewer, or just one commit, makes the commits in your pull request match the changes your update makes to the `angular/angular` repo.
## Format commit messages for a pull request
Commits merged to `angular/angular` must have messages that are correctly formatted.
This section describes how to correctly format commit messages.
Remember that the commit message is different from the pull request comment.
### Single line commit messages
The simplest commit message is a single-line of text.
All commit messages in a pull request that updates documentation must begin with `docs:` and be followed by a short description of the change.
The following is an example a valid Angular commit message.
<code-example language="none" hideCopy>
docs: a short summary in present tense without capitalization or ending period
</code-example>
This is an example of a commit command with the single-line commit message from the previous example.
<code-example format="shell" language="shell">
git commit -m "docs: a short summary in present tense without capitalization or ending period"
</code-example>
### Multi-line commit messages
You can include more information by providing a more detailed, multi-line message.
The detailed body text of the message must be separated by a blank line after the summary.
The footer that lists the issue the commit fixes must also be separated from the body text by a blank line.
<code-example language="none" hideCopy>
docs: a short summary in present tense without capitalization or ending period
A description of what was fixed, and why.
This description can be as detailed as necessary and can be written with
appropriate capitalization and punctuation
Fixes &num;34353
</code-example>
This is an example of a commit command with a multi-line commit message from the previous example.
<code-example format="shell" language="shell">
git commit -m "docs: a short summary in present tense without capitalization or ending period
A description of what was fixed, and why.
This description can be as detailed as necessary and can be
written with appropriate capitalization and punctuation.
Fixes &num;34353"
</code-example>
This example is for documentation updates only.
For the complete specification of Angular commit messages, see [Commit message format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit).
### Change a commit message
If the last commit you made has a message that isn't in the correct format, you can update the message.
Changing the message of an earlier commit or of multiple commits is also possible, but requires a more complex procedure.
Run this command to change the commit message of the most recent commit.
The new commit message is formatted as described in the previous procedures.
<code-example format="shell" language="shell">
git commit --amend -m "New commit message"
</code-example>
This command creates a new commit on your local computer that replaces the previous commit.
You must push this new commit before you open your pull request.
If you pushed the original commit to the repo in your GitHub account, run this command to force-push the commit with the new message.
<code-example format="shell" language="shell">
git push --force-with-lease
</code-example>
If you haven't pushed the commit you amended, you can run `git push` with no parameters to push your updated commit.
## Prepare your branch for a pull request
When you created your working branch to update the documentation, you branched off the `main` branch.
Your changes in the working branch were based on the state of the `main` branch at that time you created the branch.
Since you created your working branch, it's quite likely that the `main` branch has been updated.
To make sure that your updates work with the current `main` branch, you should `rebase` your working branch to catch it up to what is current.
You might also need to squash the commits you made in your working branch to combine them for the pull request.
### Rebase your working branch
<!-- markdownLint-disable MD033 -->
Rebasing your working branch changes the starting point of your commits from where the `main` branch was when you started to where it is now.
Before you can rebase your working branch, you must update both your *clone* and your *fork* of the upstream repo.
#### Why you rebase your working branch
Rebasing your working branch to the current state of the `main` branch eliminates conflicts before your working branch is merged back into `main`.
By rebasing your working branch, the commits in your working branch show only those changes that you made to fix the issue.
If you don't rebase your working branch, it can have merge commits.
Merge commits are commits that `git` creates to make up for the changes in the `main` branch since the `working` branch was created.
Merge commits aren't harmful, but they can complicate a future review of the changes.
The following illustrates the rebase process.
This image shows a `working` branch created from commit 5 of the `main` branch and then updated twice.
The numbered circles in these diagrams represent commits.
<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 a git repo with a working branch created from a main branch" src="generated/images/guide/doc-pr-prep/feature-with-new-branch.png">
</div>
This image shows the `main` branch after it was updated twice as the `working` branch was updated.
<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 a git repo with a working branch and an updated main branch" src="generated/images/guide/doc-pr-prep/feature-branch-w-update.png">
</div>
If the working branch was merged, a merge commit would be needed.
This image illustrates the result.
<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 a git repo with a working branch and merged into the main branch" src="generated/images/guide/doc-pr-prep/feature-branch-w-merge.png">
</div>
To make it easy for future contributors, the Angular team tries to keep the commit log as a linear sequence of changes.
Incorporating merge commits includes changes that are the result of the merge along with what the author or developer changed. This makes it harder for future developers and authors to tell how the content evolved.
To create a linear sequence of changes, you might need to update your `working` branch and update your changes. To add your updates to the current state of the `main` branch and prevent a merge commit, you rebase the `working` branch.
Rebasing is how `git` updates your working branch to make it look like you created it from commit `9`.
To do this, it updates the commits in the `working` branch.
After rebasing the `working` branch, its commits now start from the last commit of the `main` branch.
This image shows the rebased `working` branch with is updated commits.
<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 a git repo with an updated working branch" src="generated/images/guide/doc-pr-prep/feature-branch-w-rebase.png">
</div>
When the rebased `working` branch is merged to main, its commits can now be appended to the `main` branch with no extra merge commits.
This image shows the linear, `main` branch after merging the updated and rebased `working` branch.
<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 a git repo with an updated working branch" src="generated/images/guide/doc-pr-prep/feature-branch-merged.png">
</div>
#### To update your fork of the upstream repo
You want to sync the `main` branch of your origin repo with the `main` branch of the upstream `angular/angular` before you open a pull request.
This procedure updates your origin repo, the `personal/angular` repo, on your local computer so it has the current code, as illustrated here.
The circled numbers correspond to procedure steps.
The last step of this procedure then pushes the update to the fork of the `angular` in your GitHub account.
<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-pr-prep/github-fetch-merge.png">
</div>
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 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. 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. 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 and your origin repo on `github.com` are now in sync.
They have been updated with any changes to the upstream `angular/angular` repo that were made since the last time you updated your fork.
#### To rebase your working branch
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 format="shell" language="shell">
cd personal/angular
</code-example>
1. Run this command to check out your `working` branch.
Replace `working-branch` with the name of your `working` branch.
<code-example format="shell" language="shell">
git checkout working-branch
</code-example>
1. Run this command to rebase your branch to add the commits from your `working` branch to the current content in the `main` branch.
<code-example format="shell" language="shell">
git rebase main
</code-example>
1. Run this command to update your `working` branch in the repo in your GitHub account.
<code-example format="shell" language="shell">
git push --force-with-lease
</code-example>
### Review the commits in your working branch
After you rebase your `working` branch, your commits should be after those of the current `main` branch.
#### To review the commits that you've added to the `working` branch
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 format="shell" language="shell">
cd personal/angular
</code-example>
1. Run this command to confirm that you are using the correct `working` branch.
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.
<code-example format="shell" language="shell">
git status
</code-example>
1. Review the message from the previous `git status` command.
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.
1. Run this command to get a list of the commits in your `working` branch.
<code-example format="shell" language="shell">
git log --pretty=format:"%h %as %an %Cblue%s %Cgreen%D"
</code-example>
This command returns the log of commits in the `working` branch with the most recent commit at the top of the list.
1. In the output of the previous `git log` command, find the entry that contains `upstream/main`.
It should be near the top of the list.
1. **Confirm that the entry that contains `upstream/main` also contains `origin/main` and `main`**
If it doesn't, you must resync your clone and your fork of `angular/angular`, and then rebase the branch before you continue.
1. **Confirm that all commits for your update are after the entry that contains `upstream/main`**
Remember that the log output is displayed with the most recent commit first. Your commits should all be on top of the entry that contains `upstream/main` in the log output.
If any of your commits are listed after the entry that contains `upstream/main`, somehow your commits in the `working` branch got mixed up. You must fix the branch before you open a pull request.
1. **Confirm that your commit messages are in the correct format**
The commit message format is tested by the automated tests and it must be in the correct format before the pull request can be approved.
1. **Confirm that your commits and their messages reflect the changes your update makes to Angular**
If you have more commits than changes, you might need to squash them into fewer commits before your pull request is approved.
## Next step
After you confirm that your updates and your `working` branch are correct, you are ready to [open a pull request](guide/doc-pr-open).
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

222
aio/content/guide/doc-pr-update.md Normal file
View file

@ -0,0 +1,222 @@
# Update a documentation pull request
<!-- markdownLint-disable MD001 -->
This topic describes how to respond to test failures and feedback on your pull request.
After you open a pull request, it is tested and reviewed.
After it's approved, the changes are merged into `angular/angular` and they become part of the Angular documentation.
While some pull requests are approved with no further action on your part, most pull requests receive feedback that requires you to make a change.
## Anatomy of a pull request
After you open a pull request, the pull request page records the activity on the pull request as it is reviewed, updated, and approved.
This is an example of the top of a pull request page followed by a description of the information it contains.
<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="Screenshot of github.com page showing a branch listing from a repo" src="generated/images/guide/doc-pr-update/pull-request-heading.png">
</div>
Above the pull-request tabs is a summary of the pull request that includes:
* The pull request title and index
* The status of the pull request:
open or closed
* A description of the branch with the changes and the branch to update
The tabs contain different aspects of the pull request.
* **Conversation**
All comments and changes to the pull request, system messages, and a summary of the automated tests and approvals.
* **Commits**
The log of the commits included in this pull request.
* **Checks**
The results of the checks run on the commit.
This is different from the automated tests that are also run and summarized at the bottom of the **Conversation** tab.
* **Files changed**
The changes this request makes to the code.
In this tab is where you find specific comments to the changes in your pull request.
You can reply to those comments in this tab, as well.
## Respond to a comment
If your pull request receives comments from a reviewer, you can respond in several ways.
* Reply to the feedback.
For example, you can ask for more information or reply with an explanation.
* Make the changes to the documentation that the reviewer recommends.
If you update the working branch with the suggested changes, resolve the comment.
* Make other changes to the documentation.
After reviewing the feedback, you might see an even better improvement.
Update the working branch with your improvement and explain why you chose that to your reviewers in a comment.
Remember that pull requests that do not receive a response to a review comment are considered abandoned and closed.
For more information about abandoned pull requests, see [What happens to abandoned pull requests](guide/doc-pr-open#what-happens-to-abandoned-pull-requests).
### Update a file in the pull request
Follow this procedure to change a file in the pull request or to add a new file to the pull request.
1. In your `git` workspace, in your working directory, checkout your working branch.
1. Update the documentation to respond to the feedback you received.
The procedures used to [revise a documentation topic](guide/doc-editing) are also used to update the documentation while there's an open pull request.
1. Test your update locally as described in [Testing a documentation update](guide/doc-build-test).
1. After your updates have been tested, commit your changes and push the new commits to the working branch of your repo on your `origin` server.
1. After you update the working branch on your `origin` server, the fork of the `angular/angular` repo in your GitHub account, your pull request updates automatically.
1. After the pull request updates, the automated tests are restarted and the reviewers are notified.
Repeat this process as needed to address the feedback you get from reviews of the pull request.
## Clean up the branch
If you added commits to address review feedback, you might be requested to clean up your working branch.
If some of the commits you made address only review feedback from your reviewers, they can probably be squashed.
Squashing commits combines the changes made in multiple commits into a single commit.
<!-- markdownLint-disable MD033 -->
#### To squash commits in your working branch
Perform these steps from a command-line tool on your local computer.
1. In your [workspace](guide/doc-prepare-to-edit#create-a-git-workspace-on-your-local-computer) directory, in your [working directory](guide/doc-prepare-to-edit#doc-working-directory), checkout your working branch.
1. Run this command to view the commits in your working branch.
<code-example format="shell" language="shell">
git log --pretty=format:"%h %as %an %Cblue%s %Cgreen%D"
</code-example>
1. In the output of the previous `git log` command, find the entry that contains `upstream/main`.
It should be near the top of the list.
1. **Confirm that entry also contains `origin/main` and `main`**
If it doesn't, you must resync the clone on your local computer and your `personal/angular` repo with the `upstream` repo.
After you resync the repos, [rebase the working branch](guide/doc-pr-prep#rebase-your-working-branch) before you continue.
1. **Confirm that all commits for your update are after the entry that contains `upstream/main`**
Remember that the log output is displayed with the most recent commit first.
Your commits should all be on top of the entry that contains `upstream/main` in the log output.
If you have commits that are listed after the entry that contains `upstream/main`, somehow your commits in the working branch got mixed up.
You must fix the branch before you try to squash any commits.
1. Count the lines that are on top of the entry that contains `upstream/main`.
For example, in this log output, the working branch name is `update-doc-contribution` and there are five commit entries that are on top of the entry that contains `upstream/main`.
<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 -->
<a href="generated/images/guide/doc-pr-update/git-log-output-large.png"><img alt="Screenshot of git log output" src="generated/images/guide/doc-pr-update/git-log-output.png"></a>
</div>
1. Run this command to squash the commits that occurred after the entry that contains `upstream/main`.
In your command, replace the `5` after `HEAD` with the number of commits on top of the entry that contains `upstream/main`.
<code-example format="shell" language="shell">
git rebase -i HEAD~5
</code-example>
1. This command opens your default editor with entries for the commits that you selected in the `git rebase` command.
<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="Screenshot of git rebase editor screen" src="generated/images/guide/doc-pr-update/git-squash-edit.png">
</div>
1. To squash the commits, edit the commands in the file that's presented in the editor.
The commands in the editor are listed from oldest to newest, which is the opposite order from how they are listed by the `git log` command.
The possible command options are listed in the editor below the commands.
To squash the commits for your pull request, you only need: `pick` and `squash`.
1. Review the commands in the editor and change them to match your intention.
The commands are processed from top to bottom, that is from oldest commit to the most recent.\
To merge all commits in this branch for this pull request, change the `pick` commands to `squash` for all commits except for the first one.
This text shows how this looks for this example.
<code-example language="none" hideCopy>
pick bb0ff71891 docs: update of documentation contrib. guide
squash c040d76685 docs: more content for doc updates
squash 472585c43f docs: fix links that were broken by renamed files
squash 3e6f4c73ac docs: add more info about open PR
squash 8e50fad064 docs: more pr docs
</code-example>
With this edit, `git rebase` picks the first commit and combines the later commits into the first one.
The commit message of the commit with the `pick` command, is the commit message used for the resulting commit.
Make sure that it in the correct format and starts with `docs:`.
If you need to change the commit message, you can edit it in the editor.
1. After you update the commands, save and exit the editor.
The `git rebase` commit processes the commands and updates the commit log in your workspace.
In this example, the rebase command combined the five commits to create a single commit in your working branch.
This is the commit log after the rebase command completes.
<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 -->
<a href="generated/images/guide/doc-pr-update/git-log-after-squash-large.png"><img alt="Screenshot of commit log after git rebase command" src="generated/images/guide/doc-pr-update/git-log-after-squash.png"></a>
</div>
1. The `git rebase` command changes the commit log in your local computer so it is now different from the one in your online repo.
To update your online repo, you must force your push of changes from your local computer using this command.
<code-example format="shell" language="shell">
git push --force-with-lease
</code-example>
This action is also called a *force push* because it changes the commit log that was stored in your GitHub account.
Normally, when you run `git push`, you add new commits to the online repo.
When other people have forked a repo, a force push can have undesired effects for them.
This force-push is to your forked repo, which should not be shared, so it should be OK.
1. After your force push updates the online repo, your pull request restarts the automated tests and notifies the reviewers of the update.
## Next steps
Repeat these update steps as necessary to respond to all the feedback you receive.
After you address all the feedback and your pull request has been approved, it is merged into `angular/angular`.
The changes in your pull request should appear in the documentation shortly afterwards.
After your pull request is merged into `angular/angular`, you can [clean up your workspace](guide/doc-edit-finish).
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

425
aio/content/guide/doc-prepare-to-edit.md Normal file
View file

@ -0,0 +1,425 @@
# Prepare to edit Angular documentation
This topic describes the steps that prepare your local computer to edit and submit Angular documentation.
<div class="alert is-important">
**IMPORTANT**: <br />
To submit changes to the Angular documentation, you must have:
* A [GitHub][GithubMain] account
* A signed [Contributor License Agreement][GithubAngularAngularBlobMainContributingSigningTheCla]
</div>
## Complete a contributor's license agreement
Review [Contributing to Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md).
These sections are particularly important for documentation contributions:
1. Read the Angular [Code of conduct](https://github.com/angular/code-of-conduct/blob/main/CODE_OF_CONDUCT.md)
1. Read the [Submission guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-submission-guidelines).
<div class="alert is-helpful">
**NOTE**: <br />
The topics in this section explain these guidelines specifically for documentation contributions.
</div>
1. Read and complete the [Contributor license agreement](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-signing-the-cla) that applies to you.
## Install the required software
To edit, build, and test Angular documentation on your local computer, you need the following software.
The instructions in this section assume that you are using the software in this list to complete the tasks.
Some software in this list, such as the integrated development environment \(IDE\), can be substituted with similar software.
If you use a substitute IDE, you might need to adapt the instructions in this section to your IDE.
For more information about the required software, see [Setting up the local environment and workspace](guide/setup-local).
* **Version control software**
* [Git command line](https://github.com/git-guides/install-git)
* [GitHub desktop](https://desktop.github.com) \(optional\)
* **Integrated development environment**
* [Visual Studio Code](https://code.visualstudio.com)
* **Utility software**
* [node.js](https://nodejs.org/en/download)
Angular requires an [active long-term-support (LTS) or maintenance LTS version](https://nodejs.org/about/releases) of Node.js.
* [Yarn](https://yarnpkg.com/getting-started/install)
* [Homebrew](https://brew.sh) for macOS or [Chocolatey](https://chocolatey.org/install) for Windows
* [Vale][GithubAngularAngularTreeMainAioToolsDocLinterInstallValeOnYourDevelopmentSystemReadmeMd] \(see note\)
<div class="alert is-important">
**IMPORTANT**: <br />
Wait until after you clone your fork of the [`https://github.com/angular/angular`][GithubAngularAngular] repo to your local computer before you configure Vale settings.
</div>
You can also install other tools and IDE extensions that you find helpful.
## Set up your workspaces
The Angular documentation is stored with the Angular framework code in a GitHub source code repository, also called a *repo*, at:
[https://github.com/angular/angular](https://github.com/angular/angular).
To contribute documentation to Angular, you need:
* A GitHub account
* A *fork* of the Angular repo in your personal GitHub account.
This guide refers to your personal GitHub account as `personal`.
You must replace `personal` in a GitHub reference with your GitHub username.
The URL:
`https://github.com/personal` is not a valid GitHub account.
For convenience, this documentation uses these shorthand references:
* `angular/angular`
Refers to the Angular repo.
This is also known as the *upstream* repo.
* `personal/angular`
Refers to your personal fork of the Angular repo.
Replace `personal` with your GitHub username to identify your specific repo.
This is also known as the *origin* repo.
* A *clone* of your `personal/angular` repo on your local computer
GitHub repos are cloned into a `git` workspace on your local computer.
With this workspace and required tools, you can build, edit, and review the documentation from your local computer.
When you can build the documentation from a workspace on your local computer, you are ready to make major changes to the Angular documentation.
For more detailed information about how to set up your workspace, see [Create your repo and workspaces for Angular documentation](#create-your-repo-and-workspace-for-angular-documentation).
For more detailed information about how to build and test the documentation from your local computer, see [Build and test the Angular documentation](#build-and-test-the-angular-documentation).
## Create your repo and workspace for Angular documentation
This section describes how to create the repo and the `git` workspace necessary to edit, test, and submit changes to the Angular documentation.
<div class="alert is-important">
**IMPORTANT**: <br />
Because `git` commands are not beginner friendly, the topics in this section include procedures that should reduce the chance of `git` mishaps.
Fortunately, because you are working in your own account, even if you make a mistake, you can't harm any of the Angular code or documentation.
To follow the procedures in these topics, you must use the repo and directory configuration presented in this topic.
The procedures in these topics are designed to work with this configuration.
If you use a different configuration, the procedures in these topics might not work as expected and you could lose some of your changes.
</div>
The code and documentation for the Angular framework are stored in a public repository, or repo, on [github.com](https://github.com) in the `angular` account.
The path to the Angular repo is [https://github.com/angular/angular](https://github.com/angular/angular), hence the abbreviated name, `angular/angular`.
[GitHub](https://github.com) is a cloud service that hosts many accounts and repositories.
You can imagine the `angular/angular` repo in GitHub as shown in this image.
<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 angular/angular repo in the github.com cloud service" src="generated/images/guide/doc-prepare-to-edit/github-angular-cloud.png">
</div>
### Fork the `angular/angular` repo to your account
As a public repo, `angular/angular` is available for anyone to read and copy, but not to change.
While only specific accounts have permission to make changes to `angular/angular`, anyone with a GitHub account can request a change to it.
Change requests to `angular/angular` are called *pull requests*.
A pull request is created by one account to ask another account to pull in a change.
Before you can open a pull request, you need a forked copy of `angular/angular` in your personal GitHub account.
To get a forked copy of `angular/angular`, you fork the `angular/angular` repo into your personal GitHub account and end up with the repos shown in the following image.
From the perspective of `personal/angular`, `angular/angular` is the upstream repo and `personal/angular` is the origin repo.
<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 angular/angular repo in the github.com cloud service that was forked to a personal account" src="generated/images/guide/doc-prepare-to-edit/github-personal-cloud.png">
</div>
#### To fork the angular repo to your account
Perform this procedure in a browser.
1. Sign into your [GitHub](https://github.com) account.
If you don't have a GitHub account, [create a new account][GithubJoin] before you continue.
1. Navigate to [`https://github.com/angular/angular`][GithubAngularAngular].
1. In [`https://github.com/angular/angular`][GithubAngularAngular], click the **Fork** button near the top-right corner of the page.
This image is from the top of the [`https://github.com/angular/angular`][GithubAngularAngular] page and shows the **Fork** button.
<div class="lightbox">
<img alt="An image of the angular/angular website in github.com that identifies the fork button" src="generated/images/guide/doc-prepare-to-edit/angular-angular-github.png">
</div>
1. In **Create a new fork**:
1. Accept the default values in **Owner** and **Repository name**.
1. Confirm that **Copy the `main` branch only** is checked.
1. Click **Create repository**.
The forking process can take a few minutes.
1. You now have a copy of the `angular/angular` repo in your GitHub account.
After your fork of `angular/angular` is ready, your browser opens the web page of the forked repo in your GitHub account.
In this image, notice that the account now shows the username of your personal GitHub account instead of the `angular` account.
<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 personal/angular website in github.com that identifies the fork forked repo" src="generated/images/guide/doc-prepare-to-edit/personal-angular-github.png">
</div>
As a forked repo, your new repo maintains a reference to `angular/angular`.
From your account, `git` considers your `personal/angular` repo as the origin repo and `angular/angular` as the upstream repo.
You can think of this as: your changes originate in the *origin* repo and you send them *upstream* to the `angular/angular` repo.
The message below the repo name in your account, `forked from angular/angular`, contains a link back to the upstream repo.
This relationship comes into play later, such as when you update your `personal/angular` repo and when you open a pull request.
### Create a git workspace on your local computer
A `git` workspace on your local computer is where copies of GitHub repos in the cloud are stored on your local computer. To edit Angular documentation on your local computer, you need a clone of your origin repo, `personal/angular`.
Clone the `personal/angular` repo into the subdirectory for your account, as this illustration shows.
Remember to replace `personal` with your GitHub username.
The `personal/angular` directory in your workspace becomes your `working` directory.
You do your editing in the working directory of your `personal/angular` repo.
<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 angular repo from the angular and personal accounts in the github.com cloud service as they are cloned into local computer workspaces" src="generated/images/guide/doc-prepare-to-edit/github-clone-img.png">
</div>
Cloning a repo duplicates the repo that's in the cloud on your local computer.
There are procedures to keep the clone on your local computer in sync with the repo in the cloud that are described later.
#### To clone the Angular repo into your workspace
Perform these steps in a command-line tool on your local computer.
1. Navigate to the `workspace` directory.
In this example, this is the directory named, `github-projects`.
<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 project directory on a local computer" src="generated/images/guide/doc-prepare-to-edit/pc-directory-start-img.png">
</div>
If this directory isn't on your local computer, create it, and then navigate to it before you continue.
1. From the workspace directory, run this command to create a directory for the repo from your `personal` account
Remember to replace `personal` with your GitHub username.
<code-example format="shell" language="shell">
mkdir personal
</code-example>
1. From the workspace directory, run this command to clone the origin `personal/angular` repo into the `personal` account directory.
Remember to replace `personal` with your GitHub username.
<!-- markdownLint-disable MD034 -->
<code-example format="shell" language="shell">
git clone https://github.com/personal/angular personal/angular
</code-example>
<!-- markdownLint-enable MD034 -->
Your local computer is now configured as shown in the following illustration.
<a id="doc-working-directory"></a>
Your `working` directory is the `personal/angular` directory in your `git` workspace directory.
This directory and its subdirectories have the files that you edit to fix documentation issues.
<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-prepare-to-edit/pc-directory-config-img.png">
</div>
### Complete the software installation
After you clone the origin repo on your local computer, run these commands from a command-line tool:
1. Install the npm modules used by the Angular project.
In a command line tool on your local computer:
1. Navigate to your `git` workspace.
In this example, this is the `github-projects` directory.
1. In your `git` workspace, run this command to navigate to the documentation root directory in your clone of the `personal/angular` repo.
Remember to replace `personal` with your GitHub username.
<code-example format="shell" language="shell">
cd personal/angular/aio
</code-example>
1. Run this command to install the npm modules.
<code-example format="shell" language="shell">
yarn install
</code-example>
1. Locate `angular/aio/tools/doc-linter/vale.ini` in your working directory to use in the next step as the path to the configuration file in the **Vale:Config** setting.
1. [Install Vale][GithubAngularAngularTreeMainAioToolsDocLinterInstallValeOnYourDevelopmentSystemReadmeMd] to complete the software installation.
## Build and test the Angular documentation
Angular provides tools to build and test the documentation.
To review your work and before you submit your updates in a pull request, be sure to build, test, and verify your changes using these tools.
<div class="alert is-important">
Note that the instructions found in [https://github.com/angular/angular/blob/main/docs/DEVELOPER.md](https://github.com/angular/angular/blob/main/docs/DEVELOPER.md) are to build and test the Angular framework and not the Angular documentation.
The procedures on this page build only the Angular documentation.
You don't need to build the Angular framework to build the Angular documentation.
</div>
<!-- markdownLint-disable MD033 -->
### To navigate to the Angular documentation directory
Perform these steps from a command-line tool on your local computer.
1. Navigate to the Angular documentation in the working directory of your account in your `git` workspace on your local computer.
1. Navigate to your `git` workspace directory.
In this example, this is the `github-projects` directory.
1. Run this command to navigate to the working directory with the `angular` repo you forked to your personal account.
Remember to replace `personal` with your GitHub username.
<code-example format="shell" language="shell">
cd personal/angular
</code-example>
1. Run this command to navigate to the Angular documentation directory.
<code-example format="shell" language="shell">
cd aio
</code-example>
The Angular documentation directory is the root of the Angular documentation files.
These directories in the `angular/aio` directory are where you find the files that are edited the most.
| Directory | Files |
|:--- |:--- |
|`angular/aio/content` | Files and other assets used in the Angular documentation |
|`angular/aio/content/guide` | The markdown files for most Angular documentation |
|`angular/aio/content/tutorial` | The markdown files used by the Tour of Heroes tutorial |
The Angular documentation source has many other directories in `angular/aio` but they don't change often.
### To build and view the Angular documentation on your computer
Perform these steps from a command-line tool on your local computer.
1. Build the Angular documentation.
1. From the Angular documentation directory, run this command:
<code-example format="shell" language="shell">
yarn build
</code-example>
1. If building the documentation reports one or more errors, fix the errors and repeat the previous step before you continue.
1. Start the local documentation server.
1. From the documentation directory, run this command:
<code-example format="shell" language="shell">
yarn serve-and-sync
</code-example>
1. Open a browser on your local computer and view your documentation at `https://localhost:4200`.
1. Review the documentation in the browser.
### To run the automated tests on the Angular documentation
Perform these steps from a command-line tool on your local computer.
1. [Navigate to the documentation directory](#to-navigate-to-the-angular-documentation-directory), if you're not already there.
1. From the documentation directory, run this command to build the documentation before you test it:
<code-example format="shell" language="shell">
yarn build
</code-example>
1. If building the documentation returns one or more errors, fix those and build the documentation again before you continue.
1. From the documentation directory, run this command to start the automated tests that verify the docs are consistent.
These are most, but not all, of the tests that are performed after you open your pull request.
Some tests can only be run in the automated testing environment.
<code-example format="shell" language="shell">
yarn e2e
</code-example>
When you run these tests on your documentation updates, be sure to correct any errors before you open a pull request.
## Next steps
After you build the documentation from your forked repo on your local computer and the tests run without error, you are ready to continue.
You have successfully configured your local computer to edit Angular documentation and open pull requests.
Continue to the other topics in this section for information about how to perform other documentation tasks.
<!-- links -->
<!-- external links -->
[GithubJoin]: https://github.com/join "Join GitHub | GitHub"
[GithubMain]: https://github.com "GitHub"
[GithubAngularAngular]: https://github.com/angular/angular "angular/angular | GitHub"
[GithubAngularAngularBlobMainContributingSigningTheCla]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-signing-the-cla "Signing the CLA - Contributing to Angular | angular/angular | GitHub"
[GithubAngularAngularTreeMainAioToolsDocLinterInstallValeOnYourDevelopmentSystemReadmeMd]: https://github.com/angular/angular/tree/main/aio/tools/doc-linter/README.md#install-vale-on-your-development-system "Install Vale on your development system - Angular documentation lint tool | angular/angular | Github"
<!-- end links -->
@reviewed 2022-10-12

41
aio/content/guide/doc-select-issue.md Normal file
View file

@ -0,0 +1,41 @@
# Select a documentation issue
This topic describes how to select an Angular documentation issue to fix.
Angular documentation issues are stored in the **Issues** tab of the [angular/angular](https://github.com/angular/angular) repo.
Documentation issues can be identified by the `comp: docs` label and they are labeled by priority.
You are welcome to work on [any issue](#links-to-documentation-issues) that someone else isn't already working on.
If you know of a problem in the documentation that hasn't been reported, you can also [create a new documentation issue](https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml).
Some things to consider when choosing an issue to fix include:
* Fixing higher priority issues is more valuable to the community.
* If you're new to open source software, a lower priority issue or a `good first issue` would be a good place to start.
* Every contribution helps improve the documentation.
After you select an issue to resolve:
1. In the issue page, add `working on fix` as a comment to let others know that you are working on it.
1. Continue to [Starting to edit a documentation topic](guide/doc-update-start).
<a id="links-to-documentation-issues"/>
| Links to documentation issues |
|:--- |
| [All open documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22) |
| [All open and unassigned documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22+no%3Aassignee+-label%3A"state%3A+has+PR") |
| [Unassigned good first documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22+label%3A%22good+first+issue%22+no%3Aassignee+-label%3A"state%3A+has+PR") |
| [Unassigned priority 1 documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22+label%3Ap1+no%3Aassignee+-label%3A"state%3A+has+PR") |
| [Unassigned priority 2 documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22+label%3Ap2+no%3Aassignee+-label%3A"state%3A+has+PR") |
| [Unassigned priority 3 documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22+label%3Ap3+no%3Aassignee+-label%3A"state%3A+has+PR") |
| [Unassigned priority 4 documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22+label%3Ap4+no%3Aassignee+-label%3A"state%3A+has+PR") |
| [Unassigned priority 5 documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22+label%3Ap5+no%3Aassignee+-label%3A"state%3A+has+PR") |
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

42
aio/content/guide/doc-tasks.md Normal file
View file

@ -0,0 +1,42 @@
# Overview of documentation maintenance tasks
The Angular documentation needs routine maintenance to keep it up-to-date.
The topics in this section describe routine maintenance tasks that you can perform to help keep the Angular documentation in good condition.
Documentation maintenance tasks fall into these two categories:
* Minor changes
* Major changes
Minor changes can be made in the GitHub site without the need to load any software or tools on your system.
For information about making a minor change to the documentation, see [Make a minor change](guide/contributors-guide-overview#make-a-minor-change).
Major changes require that you build and test your changes to the documentation on your local computer before you send them to the Angular documentation.
For information about preparing your system to make major changes to the documentation, see [Make a major change](guide/contributors-guide-overview#make-a-major-change).
## Routine documentation maintenance tasks
| Task | Scope |
|:--- |:--- |
| [Review current documentation](guide/reviewing-content) | Minor \(See note\) |
| [Update search keywords](guide/updating-search-keywords) | Minor |
| [Resolve linter errors](guide/docs-lint-errors) | Major |
| [Resolve documentation issues](guide/doc-select-issue) | Major |
<div class="alert is-helpful">
**NOTE**: <br />
Reviewing current documentation requires a minor change if all you need to do is update the `@reviewed` date.
If you find a minor problem with a documentation topic, such as a typo, fixing it during your review is also a minor change.
If you find an issue that you don't feel comfortable fixing, [open a docs issue](https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml) in GitHub so someone else can fix it.
</div>
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

107
aio/content/guide/doc-update-overview.md Normal file
View file

@ -0,0 +1,107 @@
# Overview of Angular documentation editorial workflow
This section describes the process of making major changes to the Angular documentation.
It also describes how Angular documentation is stored, built, revised, and tested.
The following diagram illustrates the workflow for revising Angular documentation.
The steps are summarized below and described in the topics of this section.
<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="A block diagram that shows the steps in the writing workflow" src="generated/images/guide/doc-update-overview/writing-workflow.png">
</div>
## Prepare to edit the docs
You perform this step one time to prepare your local computer to update the Angular documentation.
For more information about how to prepare to edit the docs, see [Preparing to edit documentation](guide/doc-prepare-to-edit).
## Select a documentation issue
The first step in resolving a documentation issue is to select one to fix.
The issue that you fix can be one from the [list of documentation issues](https://github.com/angular/angular/issues?q=is%3Aissue+is%3Aopen+label%3A%22comp%3A+docs%22) in the `angular/angular` repo or one you create.
For more information about how to select an issue to fix, see [Selecting a documentation issue](guide/doc-select-issue).
### Create a documentation issue
If you want to fix a problem that has not already been described in an issue, [open a documentation issue](https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml) before you start.
When you can relate an issue to your pull request, reviewers can understand the problem better when they review your pull request.
### Create a working branch
After you select an issue to resolve, create a `working` branch in the `working` directory on your local computer.
You need to make your changes in this branch to save and test them while you edit.
After you fix the issue, you use this branch when you open the pull request for your solution to be merged into `angular/angular`.
For more information about how to create a `working` branch, see [Starting to edit a documentation topic](guide/doc-update-start).
## Revise topics
In your `working` branch, you edit and create the documentation topics necessary to resolve the issue.
You perform most of this work in your integrated development environment \(IDE\).
For more information about how to revise a documentation topic, see [Revising a documentation topic](guide/doc-editing).
### Resolve lint errors
Each time you save your edits to a documentation topic, the documentation linter reviews your topic.
It reports the problems it finds in your topic to your IDE.
To prevent delays later in the pull request process, you should correct these problems as they are reported.
The documentation linter errors must be corrected before you open the pull request to pass the pull request review.
Having lint errors in a topic can prevent the pull request from being approved for merging.
For more information about how to resolve lint problems in a documentation topic, see [Resolving documentation linter messages](guide/docs-lint-errors).
### Test your changes
As you edit documentation topics to resolve the issue you selected, you want to build a local version of the updated documentation.
This is the easiest way to review your changes in the same context as the documentation's users.
You can also run some of the automated tests on your local computer to catch other errors.
Running these tests on your local computer before you open a pull request speeds up the pull-request approval process.
For more information about how to build and test your changes before you open a pull request, see [Building and testing documentation](guide/doc-build-test).
## Prepare your pull request
To make your documentation changes ready to be added to the `angular/angular` repo, there are a few things to do before you open a pull request.
For example, to make your pull request easy to review and approve, the commits and commit messages in your `working` branch must be formatted correctly.
For information about how to prepare your branch for a pull request, see [Preparing documentation for a pull request](guide/doc-pr-prep).
### Open your pull request
Opening a documentation pull request sends your changes to the Angular reviewers who are familiar with the topic.
To be processed correctly, pull requests for `angular/angular` must be formatted correctly and contain specific information.
For information about how to format a pull request for your documentation update, see [Opening a documentation pull request](guide/doc-pr-open).
### Update your pull request
You might get feedback about your pull request that requires you to revise the topic.
Because the pull-request process is designed for all Angular code, as well as the documentation, this process might seem intimidating the first time.
For information about how to update your topics and respond to feedback on your changes, see [Updating a documentation pull request in progress](guide/doc-pr-update).
## Clean up after merge
After your pull request is approved and merged into `angular/angular`, it becomes part of the official Angular documentation.
At that point, your changes are now in the `main` branch of `angular/angular`.
This means that you can safely delete your `working` branch.
It is generally a good practice to delete `working` branches after their changes are merged into the `main` branch of `angular/angular`.
This prevents your personal fork from collecting lots of branches that could be confusing in the future.
For information about how to clean up safely after your pull request is merged, see [Finishing up a documentation pull request](guide/doc-edit-finish).
<!-- links -->
<!-- external links -->
<!-- end links -->
@reviewed 2022-10-12

175
aio/content/guide/doc-update-start.md Normal file
View file

@ -0,0 +1,175 @@
# 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

203
aio/content/guide/docs-lint-errors.md
View file

@ -1,4 +1,4 @@
# Resolving documentation linter messages
# Resolve documentation linter messages
This topic describes different ways to resolve common messages that the documentation linter produces.
@ -12,20 +12,80 @@ This is an example of a message produced by the documentation linter.
</div>
A documentation linter message contains these elements. Starting from the top line:
A documentation linter message contains these elements.
Starting from the top line:
<!-- vale Angular.Angular_Spelling = NO -->
<!-- vale Angular.Google_Spacing = NO -->
<!-- vale Angular.Google_We = NO -->
* The severity. One of these icons indicates the message's severity:
* <img alt="documentation style error icon" src="generated/images/guide/docs-lint-errors/lint-error-icon.png"> **Error** (A red `x` in a circle) Errors must be corrected before the file can be merged.
* <img alt="documentation style warning icon" src="generated/images/guide/docs-lint-errors/lint-warn-icon.png"> **Warning** (A yellow exclamation mark in a triangle) Warnings should be corrected before the file is merged.
* <img alt="documentation style info icon" src="generated/images/guide/docs-lint-errors/lint-info-icon.png"> **Info** (A blue lower-case `i` in a circle) Informational messages should be corrected before the file is merged.
* The style rule message. The style rule message in this example is: *Did you really mean 'sdfdsfsdfdfssd'? It wasn't found in our dictionary.*
* The style reference. Some references are linked to a style guide topic that explains the rule. The style reference in this example is: *Vale(Angular.Angular_Spelling)*.
* The location of the problem text in the document identified by source line and column as precisely as possible. Some messages might not have the exact location of the text that triggered the message. The location in this example is: *[Ln 8, Col 1]*.
* The style test definition file that produced the message, which is linked to the file. The style test definition in this example is: *Angular_Spelling.yml[Ln 1, Col 1]: View rule*.
* The severity.
One of these icons indicates the severity of the message:
* **Error** \(A red `x` in a circle\)
Errors must be corrected before the file can be merged.
<div class="lightbox">
<img alt="documentation style error icon" src="generated/images/guide/docs-lint-errors/lint-error-icon.png">
</div>
* **Warning** \(A yellow exclamation mark in a triangle\)
Warnings should be corrected before the file is merged.
<div class="lightbox">
<img alt="documentation style warning icon" src="generated/images/guide/docs-lint-errors/lint-warn-icon.png">
</div>
* **Info** \(A blue lower-case `i` in a circle\)
Informational messages should be corrected before the file is merged.
<div class="lightbox">
<img alt="documentation style info icon" src="generated/images/guide/docs-lint-errors/lint-info-icon.png">
</div>
* The style rule message.
The style rule message in this example is:
<code-example language="none" hideCopy>
Did you really mean 'sdfdsfsdfdfssd'? It wasn't found in our dictionary.
</code-example>
* The style reference.
Some references are linked to a style guide topic that explains the rule.
The style reference in this example is:
<code-example language="none" hideCopy>
Vale(Angular.Angular_Spelling)
</code-example>
* The location of the problem text in the document identified by source line and column as precisely as possible.
Some messages might not have the exact location of the text that triggered the message.
The location in this example is:
<code-example language="none" hideCopy>
[Ln 8, Col 1]
</code-example>
* The style test definition file that produced the message, which is linked to the file.
The style test definition in this example is:
<code-example language="none" hideCopy>
Angular_Spelling.yml[Ln 1, Col 1]: View rule
</code-example>
<!-- vale Angular.Google_We = YES -->
<!-- vale Angular.Google_Spacing = YES -->
@ -54,7 +114,7 @@ Style guides and the style tests can change.
Generally, shorter sentences are easier to read than longer ones.
Long sentences can occur when you try to say too much at once.
Long sentences, as well as the use of parentheses, semicolons, or words identified as *too-wordy*, generally require rethinking and rewriting.
Long sentences, as well as the use of parentheses, semicolons, or words identified as `too-wordy`, generally require rethinking and rewriting.
Consider restructuring a long sentence to break its individual ideas into distinct sentences or bullet points.
@ -67,7 +127,8 @@ Consider changing a comma-separated list of items in a sentence to a list of bul
### Use more common words
Shorter, more common words are generally easier to read than longer ones.
This does not mean you need to write down to the audience. Technical docs should still be precise.
This does not mean you need to write down to the audience.
Technical docs should still be precise.
Angular docs are read by many people around the world and should use language that the most people can understand.
If you think a specific term is required even though it has been flagged as uncommon, try to include a short explanation of the term.
@ -90,9 +151,10 @@ Most documentation linter messages are self-explanatory and include a link to su
Some messages identify areas in that the documentation might need more thought.
The following types of messages often occur in areas of the text that should be reconsidered and rewritten to improve the text and remove the message.
### A word is *too-wordy* or should be replaced by another
### A word is `too-wordy` or should be replaced by another
Generally, technical documentation should use a simple and consistent vocabulary to be understood by a wide audience. Words that trigger this message are usually words for which there's a simpler way to convey the same thought.
Generally, technical documentation should use a simple and consistent vocabulary to be understood by a wide audience.
Words that trigger this message are usually words for which there's a simpler way to convey the same thought.
<!-- vale Angular.Google_Spacing = NO -->
<!-- vale Angular.Google_Headings = NO -->
@ -115,50 +177,51 @@ The following table has some common words detected by this type of message and s
<!-- vale Angular.WriteGood_TooWordy = NO -->
| *Too-wordy* word | Simpler replacement |
|:-- |:-- |
|accelerate |speed up |
|accomplish |perform, finish |
|acquire |get |
|additional |more |
|adjustment |change |
|advantageous |beneficial |
|consequently |as a result |
|designate |assign |
|equivalent |the same |
|exclusively |only |
|for the most part |generally |
|have a tendency to |tend to |
|in addition |furthermore |
|modify |change or update |
|monitor |observe |
|necessitate |require |
|one particular |one |
|point in time |moment |
|portion |part |
|similar to |like |
|validate |verify |
|whether or not |whether |
| `Too-wordy` word | Simpler replacement |
|:-- |:-- |
| `accelerate` | `speed up` |
| `accomplish` | `perform` or `finish` |
| `acquire` | `get` |
| `additional` | `more` |
| `adjustment` | `change` |
| `advantageous` | `beneficial` |
| `consequently` | `as a result` |
| `designate` | `assign` |
| `equivalent` | `the same` |
| `exclusively` | `only` |
| `for the most part` | `generally` |
| `have a tendency to` | `tend to` |
| `in addition` | `furthermore` |
| `modify` | `change` or `update` |
| `monitor` | `observe` |
| `necessitate` | `require` |
| `one particular` | `one` |
| `point in time` | `moment` |
| `portion` | `part` |
| `similar to` | `like` |
| `validate` | `verify` |
| `whether or not` | `whether` |
<!-- vale Angular.WriteGood_TooWordy = YES -->
<!-- vale Angular.Google_Headings = NO -->
#### *WordList* messages
#### `WordList` messages
<!-- vale Angular.Google_Headings = YES -->
The messages about words detected by these style tests generally suggest a better alternative.
While the word you used would probably be understood, it most likely triggered this message for one of the following reasons:
* The suggested works better in a screen-reader context.
* The word that you used could produce an unpleasant response in the reader.
* The suggested word is simpler, shorter, or easier for more people to understand.
* The word you used has other possible variations. The suggested word is the variation to use in the documentation to be consistent.
* The suggested works better in a screen-reader context
* The word that you used could produce an unpleasant response in the reader
* The suggested word is simpler, shorter, or easier for more people to understand
* The word you used has other possible variations.
The suggested word is the variation to use in the documentation to be consistent.
<!-- vale Angular.Angular_Spelling = NO -->
### *Proselint* messages
### `Proselint` messages
The Proselint style tests test for words that are jargon or that could be offensive to some people.
@ -166,7 +229,7 @@ The Proselint style tests test for words that are jargon or that could be offens
Rewrite the text to replace the jargon or offensive language with more inclusive language.
### *Starting a sentence* messages
### `Starting a sentence` messages
Some words, such as *so* and *there is/are*, aren't necessary at the beginning of a sentence.
Sentences that start with the words identified by this message can usually be made shorter, simpler, and clearer by rewriting them without those openings.
@ -175,14 +238,17 @@ Sentences that start with the words identified by this message can usually be ma
Cliches should be replaced by more literal text.
Cliches make it difficult for people who don't understand English to understand the documentation. When cliches are translated by online tools such as Google Translate, they can produce confusing results.
Cliches make it difficult for people who don't understand English to understand the documentation.
When cliches are translated by online tools such as Google Translate, they can produce confusing results.
## If all else fails
The style rules generally guide you in the direction of clearer content, but sometimes you might need to break the rules.
If you decide that the best choice for the text conflicts with the linter, mark the text as an exception to linting.
The documentation linter checks only the content that is rendered as text. It does not test code-formatted text. One common source of false problems is code references that are not formatted as code.
The documentation linter checks only the content that is rendered as text.
It does not test code-formatted text.
One common source of false problems is code references that are not formatted as code.
If you use these exceptions, please limit the amount of text that you exclude from analysis to the fewest lines possible.
@ -190,58 +256,63 @@ When necessary, you can apply these exceptions to your content.
1. **General exception**
A *general exception* allows you to exclude the specified text from all lint testing.
A general exception allows you to exclude the specified text from all lint testing.
To apply a general exception, surround the text that you do not want the linter to test with the HTML
`comment` elements shown in this example.
```html
<code-example format="html" language="html">
<!-- vale off -->
&lt;!-- vale off --&gt;
Text the linter does not check for any style problem.
<!-- vale on -->
&lt;!-- vale on --&gt;
```
</code-example>
Be sure to leave a blank line before and after each comment.
2. **Style exception**
1. **Style exception**
A *style exception* allows you to exclude text from an individual style test.
A style exception allows you to exclude text from an individual style test.
To apply a style exception, surround the text that you do not want the linter to test with these HTML
`comment` elements. Between these comments, the linter ignores the style test in the comment, but
`comment` elements.
Between these comments, the linter ignores the style test in the comment, but
still tests for all other styles that are in use.
```html
<!-- vale Style.Rule = NO -->
<!-- vale Style.Rule = YES -->
```
<code-example format="html" language="html">
&lt;!-- vale Style.Rule = NO --&gt;
&lt;!-- vale Style.Rule = YES --&gt;
</code-example>
Replace `Style.Rule` in the comments with the style rule reference from the problem message displayed in the IDE.
For example, imagine that you got this problem message and you want to use the word it identified as a problem.
```html
<code-example format="html" language="html">
Did you really mean 'inlines'? It was not found in our dictionary. Vale(Angular.Angular_Spelling) [Ln 24, Col 59]
Angular_Spelling.yml[Ln 1, Col 1]: View rule
```
</code-example>
The `Style.Rule` for this message is the text inside the parentheses: `Angular.Angular_Spelling` in this case.
To turn off that style test, use the comments shown in this example.
```html
<code-example format="html" language="html">
<!-- vale Angular.Angular_Spelling = NO -->
&lt;!-- vale Angular.Angular_Spelling = NO --&gt;
'inlines' does not display a problem because this text is not spell-checked.
Remember that the linter does not check any spelling in this block of text.
The linter continues to test all other style rules.
<!-- vale Angular.Angular_Spelling = YES -->
&lt;!-- vale Angular.Angular_Spelling = YES --&gt;
```
</code-example>
<!-- links -->
@ -253,4 +324,4 @@ When necessary, you can apply these exceptions to your content.
<!-- end links -->
<!-- @reviewed 2022-07-15 -->
@reviewed 2022-10-12

2
aio/content/guide/docs-style-guide.md
View file

@ -1391,7 +1391,7 @@ A subsection with **Markdown** formatted text.
For specific language and grammar usage, a word list, style, tone, and formatting recommendations, see the [Google Developer Documentation Style Guide](https://developers.google.com/style).
If you have any questions that this style guide doesn't answer or you would like to discuss documentation styles visit the [Angular repo](https://github.com/angular/angular) and [file a documentation issue](https://github.com/angular/angular/issues/new/choose).
If you have any questions that this style guide doesn't answer or you would like to discuss documentation styles, see the [Angular repo](https://github.com/angular/angular) and [file a documentation issue](https://github.com/angular/angular/issues/new/choose).
<!-- links -->

133
aio/content/guide/reviewing-content.md
View file

@ -1,29 +1,57 @@
# Reviewing documentation
# Review documentation
You can review the Angular documentation, even if you never contributed to Angular before.
You can review the Angular documentation, even if you have never contributed to Angular before.
Reviewing the Angular documentation provides a valuable contribution to the community.
Angular developers work best when they have access to accurate and complete documentation.
Keeping existing documentation up-to-date is an essential part of ensuring that all developers have a great development experience.
Finding and reporting issues in the documentation helps the community know that the content is up to date.
Even if you don't find any problems, seeing that a document has been reviewed recently, gives readers confidence in the content.
This topic describes how you can help keep the Angular documentation up-to-date by reviewing and updating it.
This topic describes how you can review and update the Angular documentation to help keep it up to date.
## Before you begin
<!-- markdownLint-disable MD001 -->
<!-- markdownLint-disable MD033 -->
Review the [Documentation contributor guide][AioDocContributorGuide] to get ready to review to update the documentation.
The *Documentation contributor guide* describes how to prepare to update a documentation topic.
#### To review a topic in angular.io
You can edit a topic in the GitHub web interface or in your favorite code editor or integrated development environment (IDE).
In either case, you want to edit in your own fork of the Angular source code repo.
Perform these steps in a browser.
To review a documentation topic, you want to be able to edit the topic.
Even if you don't find any problem, you want to update the `@reviewed` tag at the end of the topic before you finish.
1. [Find a topic to review](#find-topics-to-review) by:
1. Finding a topic with a **Last reviewed** date that is six months or more in the past.
1. Finding a topic that has no **Last reviewed** date.
1. Finding a topic that you've read recently.
1. Review the topic for errors or inaccuracies.
1. Complete the review.
1. If the topic looks good:
1. [Update or add the `@reviewed` entry](#update-the-last-reviewed-date) at the end of the topic's source code.
1. [Make a minor change to a documentation topic](/guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic) to publish the new reviewed date.
## Finding topics to review
1. If you find an error that you don't feel comfortable fixing:
1. [Open a docs issue in GitHub](https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml).
1. [Update or add the `@reviewed` entry](#update-the-last-reviewed-date) at the end of the topic's source code.
1. [Make a minor change to a documentation topic](/guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic) to publish the new reviewed date.
Find topic a topic that has not been reviewed in the past six months.
1. If you find an error that needs only a minor change:
1. [Update or add the `@reviewed` entry](#update-the-last-reviewed-date) at the end of the topic's source code.
1. [Make a minor change to a documentation topic](/guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic) to fix the error and save the new reviewed date.
At the bottom of some topics, there's an `@reviewed` tag that shows the date it was last reviewed.
This is an example of such a tag taken from the bottom of a topic.
1. If you find an error that needs major changes:
1. Address the error:
1. [Make a major change](guide/contributors-guide-overview#make-a-major-change), if you're comfortable, or
1. [Open a docs issue in GitHub](https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml).
1. Whether you fix the error or open a new issue, [update or add the `@reviewed` entry](#update-the-last-reviewed-date) at the end of the topic's source code.
1. [Make a minor change to a documentation topic](/guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic) to save the new reviewed date.
## Find topics to review
You can review any topic in the Angular documentation, but these are the topics that benefit most from your review.
### Topics that have not been reviewed in over six months
At the bottom of some topics, there's a date that shows when the topic was last reviewed.
If that date is over six months ago, the topic is ready for a review.
This is an example of a **Last reviewed** date from the bottom of a topic.
You can also see an example of this at the end of this topic.
<div class="lightbox">
@ -31,39 +59,64 @@ This is an example of such a tag taken from the bottom of a topic.
</div>
### Topics that have never been reviewed
If a topic doesn't have a **Last reviewed** date at the bottom, it has never been reviewed.
You can review such a topic and add a new **Last reviewed** date after you review it.
### Topics that you know have a problem
If you know of a topic that has an error or inaccuracy, you can review it and make corrections during your review. If you don't feel comfortable fixing an error during your review, [open a docs issue in GitHub](https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml).
Be sure to add or update the **Last reviewed** date after you review the topic. Whether you fix the error or just open an issue, you still reviewed the topic.
## Update the last reviewed date
After you review a topic, whether you change it or not, update the topic's **Last reviewed** date.
The **Last reviewed** text at the bottom of the topic is created by the `@reviewed` tag followed by the date you reviewed the topic.
This is an example of an `@reviewed` tag at the end of the topic's source code as it appears in a code editor.
<code-example>
@reviewed 2022-09-08
</code-example>
The date is formatted as `YYYY-MM-DD` where:
* `YYYY` is the current year
* `MM` is the two-digit number of the current month with a leading zero if the month is 01 (January) through 09 (September)
* `DD` is the two-digit number of the current day of the month with a leading zero if the day is 01-09.
For example:
| Review date | `@reviewed` tag | Resulting text displayed in the docs
|:--- |:--- |:---
| January 12, 2023 | `@reviewed 2023-01-12` | *Last reviewed on Thu Jan 12, 2023*
| November 3, 2022 | `@reviewed 2022-11-03` | *Last reviewed on Fri Nov 03, 2022*
## Reviewing and updating a topic
To review a topic, use either the GitHub user interface or directly edit the source markdown file of the topic on your own computer.
These are the actions you can take after you review a topic.
Feel free to review any topic in which you have interest.
Experience with the subject matter is helpful, but not required to provide copy edits.
### The topic is accurate and has no errors
**To review and update a documentation topic:**
If the topic is accurate and has no errors, [make a minor change](/guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic) to [update the **Last reviewed** date](#update-the-last-reviewed-date) at the bottom of the page. You can use the GitHub user interface to edit the topic's source code.
1. In your web browser, navigate to the topic that you want to review.
2. Locate the last reviewed date at the bottom of the topic. Verify that the topic has not been reviewed within the past six months.
3. Read through the topic.
4. If the topic requires an update, you can:
* [File an issue][GithubAngularAngularBlobMainContributingMdSubmitIssue] that describes the update required.
* Fix the issue and [create a pull request][GithubAngularAngularBlobMainContributingMdSubmitPr] with the update.
5. If the topic is accurate and doesn't need any revision, update, or add the `@reviewed` tag followed by the date you reviewed the topic. You can do this:
* By using the [GitHub user interface][AioGuideUpdatingContentGithubUi]
* By editing the file on your computer and creating a [standard pull request process][GithubAngularAngularBlobMainContributingMdSubmitPr] for Angular.
### The topic requires minor changes
If the topic has minor errors, you can fix them when you [make a minor change](/guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic). Remember to [update the **Last reviewed** date](#update-the-last-reviewed-date) at the bottom of the page when you fix the error. For a minor change, you can use the GitHub user interface in a browser to edit the topic's source code.
### The topic requires major changes
If the topic requires major changes, you can [make a major change](guide/contributors-guide-overview#make-a-major-change), or [open a docs issue in GitHub](https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml). You shouldn't make major changes in the GitHub user interface because it doesn't allow you to test them before you submit them.
Whether you make the changes the topic needs or open a docs issue, you should still [update the **Last reviewed** date](#update-the-last-reviewed-date). You can use the GitHub user interface in the browse if you only want to update the **Last reviewed** date.
<!-- links -->
[AioDocContributorGuide]: guide/contributors-guide-overview "Documentation contributors guide | Angular"
[AioGuideReviewingContentReviewCriteria]: guide/reviewing-content#review-criteria "Review criteria - Reviewing content | Angular"
[AioGuideUpdatingContentGithubUi]: guide/updating-content-github-ui "Updating topics through the GitHub user interface | Angular"
<!-- external links -->
[GithubAngularAngularBlobMainContributingMd]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md "Contributing to Angular | angular/angular | Github"
[GithubAngularAngularBlobMainContributingMdSubmitIssue]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-issue "Submitting an Issue - Contributing to Angular | angular/angular | GitHub"
[GithubAngularAngularBlobMainContributingMdSubmitPr]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-pr "Submitting a Pull Request (PR) - Contributing to Angular | angular/angular | GitHub"
<!-- end links -->
@reviewed 2022-08-08
@reviewed 2022-10-12

47
aio/content/guide/updating-content-github-ui.md
View file

@ -1,49 +1,6 @@
# Updating topics through the GitHub user interface
This topic describes how to submit pull requests to the Angular repository using GitHub's user interface.
If you are unfamiliar with [Git](https://git-scm.com), you might find this process easier for making changes.
<div class="alert is-important">
Using the GitHub user interface for updates is recommended only for small changes to one file at a time, such as fixing typos, [updating the review date](guide/reviewing-content) or [updating search keywords](guide/updating-search-keywords).
</div>
**To update a topic through the GitHub user interface:**
1. Navigate to the topic for which you want to file a pull request.
1. Click the edit icon at the top of the topic.
<div class="lightbox">
<img alt="The edit icon for an Angular topic." src="generated/images/guide/contributors-guide/edit-icon.png">
</div>
A GitHub page appears, displaying the source of the topic.
1. Update the topic.
1. At the bottom of the screen, update the **Commit changes** box with a description of the change.
Use the format `docs: <short-description-of-change>`, where `<short-description-of-change>` briefly describes your change.
Keep the description under 100 characters.
For example:
<code-example format="github" language="markdown">
docs: fix typo in Tour of Heroes pt.1
</code-example>
1. Verify that the **create new branch** option is selected, then click **Commit changes**.
A Pull Request screen opens.
1. Fill out the form in the Pull Request screen.
At a minimum, put an `x` in the **Docs have been added / updated** option and the **Documentation content changes** option.
1. Click **Create pull request**.
At this point, your pull request is added to a list of current requests, which the documentation team reviews weekly.
This topic has been replaced by [Make a minor change](guide/contributors-guide-overview#make-a-minor-change).
<!-- links -->
@ -51,4 +8,4 @@ At this point, your pull request is added to a list of current requests, which t
<!-- end links -->
@reviewed 2022-02-28
@reviewed 2022-10-12

52
aio/content/guide/updating-search-keywords.md
View file

@ -1,46 +1,32 @@
# Updating search keywords
# Update search keywords
In documentation, being able to find the content you need is as important as the content itself.
In [angular.io](https://angular.io), users can discover content in several ways, including:
You can help readers find the topics in the Angular documentation by adding keywords to a topic.
Keywords help readers find topics by relating alternate terms and related concepts to a topic.
* Organic search results, such as through [google.com](https://google.com)
* The left navigation bar, also known as sidenav
* Using the search box in the header
In [angular.io](https://angular.io), readers search for content by using:
You can help improve the documentation experience by adding search keywords to a given topic.
Updating search keywords can help bring users to the content they need faster.
* External search, such as by using [google.com](https://google.com)
* The search box at the top of each page
## Before you begin
Each of these methods can be made more effective by adding relevant keywords to the topics.
You can update search keywords for a topic even if you've never contributed to Angular before.
However, you may find it helpful to have the [Contributing to Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md) guide available if you're filing your first pull request in the repository.
## To update search keywords in a topic
## Updating search keywords
Perform these steps in a browser.
To update search keywords:
1. Navigate to the topic to which you want to add or update search keywords.
1. Decide what search keywords you'd like to add to the topic.<br />Keywords should be words that relate to the topic and are not found in the topic headings.
1. Open the topic's **Edit file** page to [make a minor change](guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic).
1. Add or update the `@searchKeywords` tag at the end of the topic with your keywords. The `@searchKeywords` tag takes a set of single-word keywords that are separated by spaces. The tag and the keywords must be enclosed in curly brackets. A sample tag is shown here to add these keywords to a page: *route*, *router*, *routing*, and *navigation*.
1. Navigate to the topic to which you want to update search keywords.
1. Decide what search keywords you'd like to add to the topic.
For information on how to format keywords, see [Search keywords format](#format).
<code-example>
1. Update the `@searchKeywords` tag, either through the [GitHub user interface](guide/updating-content-github-ui) or through Angular's [standard pull request process](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-pr).
&lcub;&commat;searchKeywords route router routing navigation&rcub;
If a topic does not have a `@searchKeywords` tag, you can add it to the end of the topic.
</code-example>
<a id="format"></a>
## Search keywords format
You add search keywords to a topic using the `@searchKeywords` tag.
This tag takes a set of single words, separated by spaces.
The tag and the keywords must be enclosed in curly bracket \(`{` `}`\) characters.
For example:
<code-example>
&lcub;&commat;searchKeywords route router routing navigation&rcub;
</code-example>
1. [Update or add the `@reviewed` entry](guide/reviewing-content#update-the-last-reviewed-date) at the end of the topic's source code.
1. Propose your changes from as described in [make a minor change](guide/contributors-guide-overview#to-make-a-minor-change-to-a-documentation-topic).
<!-- links -->
@ -48,4 +34,4 @@ For example:
<!-- end links -->
@reviewed 2022-02-28
@reviewed 2022-10-12

BIN
aio/content/images/guide/doc-github-tasks/feature-branch-ff.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
aio/content/images/guide/doc-github-tasks/feature-branch-w-update.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
aio/content/images/guide/doc-github-tasks/feature-with-new-branch.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
aio/content/images/guide/doc-github-tasks/github-fetch-merge.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 73 KiB

BIN
aio/content/images/guide/doc-github-tasks/github-sync-upstream.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
aio/content/images/guide/doc-github-tasks/main-branch.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.9 KiB

BIN
aio/content/images/guide/doc-github-tasks/pc-directory-config.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
aio/content/images/guide/doc-pr-open/github-branch-diff.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 87 KiB

BIN
aio/content/images/guide/doc-pr-open/github-branch-view.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
aio/content/images/guide/doc-pr-open/github-recent-push.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 108 KiB

BIN
aio/content/images/guide/doc-pr-open/pr-checklist.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 120 KiB

BIN
aio/content/images/guide/doc-pr-prep/feature-branch-merged.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 8.8 KiB

BIN
aio/content/images/guide/doc-pr-prep/feature-branch-w-merge.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
aio/content/images/guide/doc-pr-prep/feature-branch-w-rebase.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
aio/content/images/guide/doc-pr-prep/feature-branch-w-update.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
aio/content/images/guide/doc-pr-prep/feature-with-new-branch.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
aio/content/images/guide/doc-pr-prep/github-fetch-merge.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
aio/content/images/guide/doc-pr-prep/github-sync-upstream.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
aio/content/images/guide/doc-pr-update/git-log-after-squash-large.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 147 KiB

BIN
aio/content/images/guide/doc-pr-update/git-log-after-squash.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
aio/content/images/guide/doc-pr-update/git-log-output-large.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 161 KiB

BIN
aio/content/images/guide/doc-pr-update/git-log-output.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 63 KiB

BIN
aio/content/images/guide/doc-pr-update/git-squash-edit.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
aio/content/images/guide/doc-pr-update/pull-request-heading.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 73 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/angular-angular-github.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/doc-prepare-to-edit.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/github-angular-cloud.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/github-clone-img.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/github-personal-cloud.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/pc-directory-config-img.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/pc-directory-start-img.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
aio/content/images/guide/doc-prepare-to-edit/personal-angular-github.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
aio/content/images/guide/doc-update-overview/writing-workflow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
aio/content/images/guide/doc-update-start/github-fetch-merge.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
aio/content/images/guide/doc-update-start/github-sync-upstream.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
aio/content/images/guide/doc-update-start/pc-directory-config.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 21 KiB

96
aio/content/navigation.json
View file

@ -1184,7 +1184,7 @@
]
},
{
"title": "Documentation contributor guide",
"title": "Documentation contributors guide",
"tooltip": "Describes how to contribute to the Angular documentation.",
"children": [
{
@ -1193,30 +1193,92 @@
"tooltip": "Provides an overview of how to contribute to Angular's documentation."
},
{
"url": "guide/reviewing-content",
"title": "Reviewing documentation",
"tooltip": "Keep Angular content up-to-date by reviewing topics for accuracy."
"title": "Common documentation maintenance tasks",
"tooltip": "Describes the Angular documentation maintenance tasks.",
"children": [
{
"url": "guide/doc-tasks",
"title": "Overview",
"tooltip": "Overview of common tasks used to maintain angular.io."
},
{
"url": "guide/reviewing-content",
"title": "Review documentation",
"tooltip": "Keep Angular content up-to-date by reviewing topics for accuracy."
},
{
"url": "guide/updating-search-keywords",
"title": "Update search keywords",
"tooltip": "Help users find the content they need by adding additional search keywords."
}
]
},
{
"url": "guide/updating-search-keywords",
"title": "Updating search keywords",
"tooltip": "Help users find the content they need by adding additional search keywords."
},
{
"url": "guide/updating-content-github-ui",
"title": "Updating content using GitHub UI",
"tooltip": "Update topics in the browser through the GitHub user interface."
"title": "Documentation editing workflow",
"tooltip": "Describes the documentation editing processes in detail.",
"children": [
{
"url": "guide/doc-update-overview",
"title": "Overview",
"tooltip": "An overview of documentation authoring process."
},
{
"url": "guide/doc-prepare-to-edit",
"title": "Prepare to edit documentation",
"tooltip": "Set up your development system to edit angular.io."
},
{
"url": "guide/doc-select-issue",
"title": "Select a documentation issue",
"tooltip": "The procedures used to identify and select a documenation issue."
},
{
"url": "guide/doc-update-start",
"title": "Start to edit a documentation topic",
"tooltip": "The procedures used to start editing a documentation topic."
},
{
"url": "guide/doc-editing",
"title": "Make and save changes to a documentation topic",
"tooltip": "Making and saving changes to a documentation topic."
},
{
"url": "guide/docs-lint-errors",
"title": "Resolve documentation linter messages",
"tooltip": "More information about documentation lint errors."
},
{
"url": "guide/doc-build-test",
"title": "Build and test documentation",
"tooltip": "Building and testing documentation."
},
{
"url": "guide/doc-pr-prep",
"title": "Prepare documentation for a pull request",
"tooltip": "Preparing documentation for a pull request."
},
{
"url": "guide/doc-pr-open",
"title": "Open a documentation pull request",
"tooltip": "Opening a documentation pull request."
},
{
"url": "guide/doc-pr-update",
"title": "Update a documentation pull request in progress",
"tooltip": "Updating a documentation pull request in progress."
},
{
"url": "guide/doc-edit-finish",
"title": "Finish up a documentation pull request",
"tooltip": "Finishing up a documentation pull request."
}
]
},
{
"url": "guide/docs-style-guide",
"title": "Documentation style guide",
"tooltip": "Style guide for documentation authors."
},
{
"url": "guide/docs-lint-errors",
"title": "Resolving documentation linter messages",
"tooltip": "More information about documentation lint errors."
},
{
"url": "guide/localizing-angular",
"title": "Angular doc localization guidelines",

BIN
aio/src/assets/images/doc-contribute-images.sketch Normal file
View file

Binary file not shown.