Minor fixes and cleanup for security advisories page (#5485)

Follow-up to #5480

Fixes #5458

A few things:

- Adjusts the placeholder redirect to point to the new page
- Add a cross-link from the pubspec reference page
- Fixes a few typos
- Use descriptive link text instead of "Here"
- Remove `/en` from the GitHub link, so it's more likely redirect to the
desired language of the user
- In the "Ignoring security advisories" section, if putting the pubspec
field `ignored_advisories` in code font, it's not really "a list of
`ignored_advisories`, but rather a list itself.
- Uses proper capitalization for "GitHub"
- Use "the Dart team" instead of "we" for the recommendation
- Some other minor wording adjustments _(please take a look :])_

firebase.json

@@ -182,7 +182,7 @@
       { "source": "/go/publishing-with-service-account", "destination": "/tools/pub/automated-publishing#publishing-from-google-cloud-build", "type": 301 },
       { "source": "/go/sdk-constraint", "destination": "/tools/pub/pubspec#sdk-constraints", "type": 301 },
       { "source": "/go/sdk-version-pinning", "destination": "https://github.com/dart-lang/sdk/wiki/Flutter-Pinned-Packages", "type": 301 },
-      { "source": "/go/pub-security-advisories", "destination": "https://github.com/dart-lang/site-www/issues/5458", "type": 301 },
+      { "source": "/go/pub-security-advisories", "destination": "/tools/pub/security-advisories", "type": 301 },
       { "source": "/go/test-docs/:page*", "destination": "https://github.com/dart-lang/test/blob/master/pkgs/test/doc/:page*", "type": 301 },
       { "source": "/go/unsound-null-safety", "destination": "/null-safety/unsound-null-safety", "type": 301 },
 

src/tools/pub/pubspec.md

@@ -94,6 +94,10 @@ A pubspec can have the following fields:
 : Optional. List of topics for the package.
   [_Learn more._](#topics)
 
+`ignored_advisories`
+: Optional. List of ignored security advisories.
+  [_Learn more._](/tools/pub/security-advisories)
+
 Pub ignores all other fields.
 
 {{site.alert.flutter-note}}

src/tools/pub/security-advisories.md

@@ -1,17 +1,22 @@
 ---
 title: Security advisories
-description: Use security advisories to inform and be informed about security vulnerabilities.
+description: >-
+  Use security advisories to inform and be informed
+  about security vulnerabilities in Dart packages.
 ---
 
 Security advisories are a means to report information about security
-vulnerabilities. Pub uses the [Github Advisory Database][]
+vulnerabilities. Pub uses the [GitHub Advisory Database][]
 for publishing security advisories for Dart and Flutter packages. 
 
-To create an advisory in your Github repository, use Github's security advisory
-reporting mechanism as explained [here][].
+To create an advisory in your GitHub repository, use
+GitHub's security advisory reporting mechanism as
+explained in GitHub's docs on [Creating a repository security advisory][].
 First you create a draft security advisory, which will then be reviewed by
-Github and ingested into the central database.
+GitHub and ingested into the central advisory database.
 
+[GitHub Advisory Database]: https://github.com/advisories
+[Creating a repository security advisory]: https://docs.github.com/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory
 
 ## Security advisories in the pub client
 
@@ -27,16 +32,19 @@ Dependencies are affected by security advisories:
   [^0]: https://github.com/advisories/GHSA-4rgh-jx4f-qfcq
 ```
 
-In such a case we recommend you follow the link and review the advisory. After
-reviewing, if you asses that this vulnerability is affecting your package, you
-should strongly consider upgrading to another version of your dependency.
+If resolution identifies an advisory, the Dart team recommends you
+visit the link and review the advisory.
+If you assess that the vulnerability affects your package, you
+should strongly consider upgrading to a non-affected version of the dependency.
 
 
 ### Ignoring security advisories
 
-If a security advisory is not relevant for your application, you can suppress the
-warning by adding the advisory to the list of `ignored_advisories` in the
-`pubspec.yaml` of your package. For example:
+If a security advisory is not relevant for your application,
+you can suppress the warning by adding the advisory identifier to
+the `ignored_advisories` list in the `pubspec.yaml` of your package.
+For example, the following ignores the advisory
+with the CVE identifier `GHSA-4rgh-jx4f-qfcq`:
 
 ```yaml
 name: myapp
@@ -46,9 +54,6 @@ ignored_advisories:
  - GHSA-4rgh-jx4f-qfcq
 ```
 
-The list of `ignored_advisories` only affects the root package. Ignored
-advisories in your dependencies will have no effect on your resolution.
-
-[Github Advisory Database]: https://github.com/advisories
-[here]: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory
-
+The `ignored_advisories` list only affects the root package. Ignored
+advisories in your dependencies will have no effect on package resolution
+for your own packages.