From a838de82830556d3fecf74a7060f75c9914599f3 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Tue, 19 Nov 2024 06:03:11 +0800
Subject: [PATCH] Move general packages doc out of guides directory (#6216)

Contributes to https://github.com/dart-lang/site-www/issues/5767
---
 firebase.json                                   | 10 +++++-----
 src/_data/side-nav.yml                          |  2 +-
 src/content/guides/libraries/create-packages.md |  4 ++--
 src/content/language/libraries.md               |  2 +-
 src/content/language/macros.md                  |  2 +-
 src/content/resources/dart-3-migration.md       |  4 ++--
 src/content/resources/useful-packages.md        |  2 +-
 src/content/security.md                         |  2 +-
 src/content/tools/index.md                      |  2 +-
 src/content/tools/pub/cmd/index.md              |  2 +-
 src/content/tools/pub/cmd/pub-get.md            |  2 +-
 src/content/tools/pub/dependencies.md           |  2 +-
 src/content/tools/pub/glossary.md               |  2 +-
 src/content/tools/pub/package-layout.md         |  2 +-
 src/content/{guides => tools/pub}/packages.md   |  0
 src/content/tools/pub/publishing.md             |  2 +-
 src/content/tools/pub/pubspec.md                |  2 +-
 src/content/tools/pub/versioning.md             |  2 +-
 src/content/tutorials/index.md                  |  2 +-
 src/content/tutorials/server/cmdline.md         |  4 ++--
 src/content/tutorials/server/get-started.md     |  2 +-
 21 files changed, 27 insertions(+), 27 deletions(-)
 rename src/content/{guides => tools/pub}/packages.md (100%)

diff --git a/firebase.json b/firebase.json
index 5815f7a5fa..de914b0d58 100644
--- a/firebase.json
+++ b/firebase.json
@@ -150,7 +150,7 @@
       { "source": "/docs/tutorials/httpserver", "destination": "/tutorials/server/httpserver", "type": 301 },
       { "source": "/docs/tutorials/indexeddb{,/**}", "destination": "https://api.dart.dev/stable/dart-indexed_db/dart-indexed_db-library.html", "type": 301 },
       { "source": "/docs/tutorials/remove-elements", "destination": "/library/dart-html", "type": 301 },
-      { "source": "/docs/tutorials/shared-pkgs", "destination": "/guides/packages", "type": 301 },
+      { "source": "/docs/tutorials/shared-pkgs", "destination": "/tools/pub/packages", "type": 301 },
       { "source": "/docs/tutorials/streams", "destination": "/libraries/async/using-streams", "type": 301 },
       { "source": "/docs/tutorials{,/**}", "destination": "/tutorials", "type": 301 },
       { "source": "/docs{,/**}", "destination": "/guides", "type": 301 },
@@ -236,6 +236,7 @@
       { "source": "/guides/libraries/c-interop", "destination": "/interop/c-interop", "type": 301 },
       { "source": "/guides/libraries/writing-package-pages", "destination": "/tools/pub/writing-package-pages", "type": 301 },
       { "source": "/guides/libraries/useful-libraries", "destination": "/resources/useful-packages", "type": 301 },
+      { "source": "/guides/packages", "destination": "/tools/pub/packages", "type": 301 },
       { "source": "/guides/platforms", "destination": "/overview#platform", "type": 301 },
       { "source": "/guides/whats-new", "destination": "/resources/whats-new", "type": 301 },
       { "source": "/install", "destination": "/get-dart", "type": 301 },
@@ -361,7 +362,7 @@
       { "source": "/support{,/**}", "destination": "/community", "type": 301 },
 
       { "source": "/to/doc-comment-references", "destination": "/tools/doc-comments/references", "type": 301 },
-      { "source": "/to/enforce-lockfile", "destination": "/guides/packages#get-dependencies-for-production", "type": 301 },
+      { "source": "/to/enforce-lockfile", "destination": "/tools/pub/packages#get-dependencies-for-production", "type": 301 },
       { "source": "/to/main-function", "destination": "/language/functions#main", "type": 301 },
       { "source": "/to/web-debug-extension", "destination": "https://chromewebstore.google.com/detail/dart-debug-extension/eljbmlghnomdjgdjmbdekegdkbabckhm", "type": 301 },
 
@@ -388,7 +389,6 @@
       { "source": "/tools/editor{,/**}", "destination": "/tools", "type": 301 },
       { "source": "/tools/faq", "destination": "/resources/faq", "type": 301 },
       { "source": "/tools/observatory{,/**}", "destination": "/tools/dart-devtools", "type": 301 },
-      { "source": "/tools/pub", "destination": "/tools/pub/cmd", "type": 301 },
       { "source": "/tools/pub/assets-and-*transformers", "destination": "https://github.com/dart-lang/build", "type": 301 },
       { "source": "/tools/pub/cmd/pub-build", "destination": "/tools/webdev", "type": 301 },
       { "source": "/tools/pub/cmd/pub-run", "destination": "/tools/dart-run", "type": 301 },
@@ -396,7 +396,7 @@
       { "source": "/tools/pub/cmd/pub-uploader", "destination": "/tools/pub/publishing#uploaders", "type": 301 },
       { "source": "/tools/pub/create-library-packages", "destination": "/guides/libraries/create-packages", "type": 301 },
       { "source": "/tools/pub/faq", "destination": "/tools/faq#pub", "type": 301 },
-      { "source": "/tools/pub/get-started", "destination": "/guides/packages", "type": 301 },
+      { "source": "/tools/pub/get-started", "destination": "/tools/pub/packages", "type": 301 },
       { "source": "/tools/pub/installing", "destination": "/tools/pub/environment-variables", "type": 301 },
       { "source": "/tools/pub/transformers{,/**}", "destination": "https://github.com/dart-lang/build", "type": 301 },
       { "source": "/tools/sdk/archive", "destination": "/get-dart/archive", "type": 301 },
@@ -408,7 +408,7 @@
       { "source": "/tutorials/language/futures", "destination": "/libraries/async/async-await", "type": 301 },
       { "source": "/tutorials/language/streams", "destination": "/libraries/async/using-streams", "type": 301 },
       { "source": "/tutorials/libraries", "destination": "/libraries", "type": 301 },
-      { "source": "/tutorials/libraries/shared-pkgs", "destination": "/guides/packages", "type": 301 },
+      { "source": "/tutorials/libraries/shared-pkgs", "destination": "/tools/pub/packages", "type": 301 },
       { "source": "/tutorials/web", "destination": "/web/get-started", "type": 301 },
       { "source": "/tutorials/web/fetch-data", "destination": "/tutorials/server/fetch-data", "type": 301 },
       { "source": "/tutorials/web/get-started", "destination": "/web/get-started", "type": 301 },
diff --git a/src/_data/side-nav.yml b/src/_data/side-nav.yml
index b4b38f1162..307534f364 100644
--- a/src/_data/side-nav.yml
+++ b/src/_data/side-nav.yml
@@ -154,7 +154,7 @@
   expanded: false
   children:
     - title: How to use packages
-      permalink: /guides/packages
+      permalink: /tools/pub/packages
     - title: Commonly used packages
       permalink: /resources/useful-packages
     - title: Creating packages
diff --git a/src/content/guides/libraries/create-packages.md b/src/content/guides/libraries/create-packages.md
index 32b9af0657..44e686fad4 100644
--- a/src/content/guides/libraries/create-packages.md
+++ b/src/content/guides/libraries/create-packages.md
@@ -3,7 +3,7 @@ title: Creating packages
 description: Learn how to create packages in Dart.
 ---
 
-The Dart ecosystem uses [packages](/guides/packages)
+The Dart ecosystem uses [packages](/tools/pub/packages)
 to share software such as libraries and tools.
 This page tells you how to create a standard shared 
 [package](/tools/pub/glossary#package).
@@ -300,7 +300,7 @@ Use the following resources to learn more about packages:
 
 * [Libraries and imports](/language/libraries) covers
   using library files.
-* The [package](/guides/packages) documentation is useful, particularly the
+* The [package](/tools/pub/packages) documentation is useful, particularly the
   [package layout conventions](/tools/pub/package-layout).
 * [What not to commit](private-files)
   covers what should not be checked into a source code repository.
diff --git a/src/content/language/libraries.md b/src/content/language/libraries.md
index e932ba76b4..a87a716663 100644
--- a/src/content/language/libraries.md
+++ b/src/content/language/libraries.md
@@ -16,7 +16,7 @@ are a unit of privacy: identifiers that start with an underscore (`_`)
 are visible only inside the library. *Every Dart file (plus its parts) is a
 [library][]*, even if it doesn't use a [`library`](#library-directive) directive.
 
-Libraries can be distributed using [packages](/guides/packages).
+Libraries can be distributed using [packages](/tools/pub/packages).
 
 :::note
 To learn why Dart uses underscores instead of access modifier keywords
diff --git a/src/content/language/macros.md b/src/content/language/macros.md
index f2bdceef06..729bd46df7 100644
--- a/src/content/language/macros.md
+++ b/src/content/language/macros.md
@@ -82,7 +82,7 @@ and a `fromJson` deserialization constructor.
    ```
 
 [SDK constraint]: /tools/pub/pubspec#sdk-constraints
-[Add the package]: /guides/packages
+[Add the package]: /tools/pub/packages
 [Enable the experiment]: /tools/experiment-flags#using-experiment-flags-with-the-dart-analyzer-command-line-and-ide
 
 ### Use the macro
diff --git a/src/content/resources/dart-3-migration.md b/src/content/resources/dart-3-migration.md
index 653752cfe1..165837e631 100644
--- a/src/content/resources/dart-3-migration.md
+++ b/src/content/resources/dart-3-migration.md
@@ -26,7 +26,7 @@ The potentially breaking changes listed below fall into one of two categories:
   language version is set to >= Dart 3.0. 
   The [language version](/guides/language/evolution#language-version-numbers)
   is derived from the `sdk` lower-constraint in the
-  [`pubspec.yaml` file](/guides/packages#creating-a-pubspec). 
+  [`pubspec.yaml` file](/tools/pub/packages#creating-a-pubspec). 
   An SDK constraint like this does *not* apply the Dart 3 versioned changes:
 
   ```yaml
@@ -52,7 +52,7 @@ later are likely backwards compatible with Dart 3.
 This is possible for any package where 
 the lower bound of the SDK constraint is 2.12.0 or higher. 
 
-[Dart's pub tool](/guides/packages) allows resolution even when
+[Dart's pub tool](/tools/pub/packages) allows resolution even when
 the upper bound is limited to versions below 3.0.0. 
 For example, a package with the following constraint
 will be allowed to resolve with a Dart 3.x SDK, 
diff --git a/src/content/resources/useful-packages.md b/src/content/resources/useful-packages.md
index 29f8e27ccd..6e62f9a192 100644
--- a/src/content/resources/useful-packages.md
+++ b/src/content/resources/useful-packages.md
@@ -8,7 +8,7 @@ description: >-
 {% assign pubpkg = site.pub-pkg %}
 
 This page lists some of the most popular and useful
-[packages](/guides/packages) that Dart developers have published.
+[packages](/tools/pub/packages) that Dart developers have published.
 To find more packages—and search [core libraries](/libraries)
 as well—use the [pub.dev site.]({{pub}})
 
diff --git a/src/content/security.md b/src/content/security.md
index 4724d2f94d..90ffcea081 100644
--- a/src/content/security.md
+++ b/src/content/security.md
@@ -91,4 +91,4 @@ mailing list.
 [Google's security philosophy]: https://www.google.com/about/appsecurity/
 [https://g.co/vulnz]: https://g.co/vulnz
 [repos]: {{site.repo.dart.org}}/
-[upgrade your package dependencies]: /guides/packages#upgrading-a-dependency
+[upgrade your package dependencies]: /tools/pub/packages#upgrading-a-dependency
diff --git a/src/content/tools/index.md b/src/content/tools/index.md
index 8fd049cf65..8bbb2d844a 100644
--- a/src/content/tools/index.md
+++ b/src/content/tools/index.md
@@ -92,7 +92,7 @@ The Dart SDK includes the following general-purpose `dart` tool:
 [`dart`](/tools/dart-tool)
 : A command-line interface (CLI) for creating, formatting, analyzing,
   testing, documenting, compiling, and running Dart code,
-  as well as working with the [pub package manager](/guides/packages).
+  as well as working with the [pub package manager](/tools/pub/packages).
 
 
 ### Debugging
diff --git a/src/content/tools/pub/cmd/index.md b/src/content/tools/pub/cmd/index.md
index ec3b0fbc53..51a204c137 100644
--- a/src/content/tools/pub/cmd/index.md
+++ b/src/content/tools/pub/cmd/index.md
@@ -3,7 +3,7 @@ title: dart pub
 description: The command-line interface for pub, a package management tool for Dart.
 ---
 
-The [pub package manager](/guides/packages) has a command-line interface
+The [pub package manager](/tools/pub/packages) has a command-line interface
 that works with either the
 [`flutter` tool][flutter-cli] or the [`dart` tool][dart-cli].
 With either tool, add the `pub` command followed by
diff --git a/src/content/tools/pub/cmd/pub-get.md b/src/content/tools/pub/cmd/pub-get.md
index 6596c1297b..2b9f6dbf13 100644
--- a/src/content/tools/pub/cmd/pub-get.md
+++ b/src/content/tools/pub/cmd/pub-get.md
@@ -158,7 +158,7 @@ package has changed.
 
 Useful for CI or deploying to production.
 
-Read [Get dependencies for production](/guides/packages#get-dependencies-for-production)
+Read [Get dependencies for production](/tools/pub/packages#get-dependencies-for-production)
 for more details.
 
 {% render 'pub-problems.md' %}
diff --git a/src/content/tools/pub/dependencies.md b/src/content/tools/pub/dependencies.md
index 7168021583..196b70a576 100644
--- a/src/content/tools/pub/dependencies.md
+++ b/src/content/tools/pub/dependencies.md
@@ -558,7 +558,7 @@ to differentiate versions. <a href="#fnref:semver">↩</a>
 </aside>
 
 [GitHub SSH]: https://help.github.com/articles/connecting-to-github-with-ssh/
-[pub package manager]: /guides/packages
+[pub package manager]: /tools/pub/packages
 [`dart pub get`]: /tools/pub/cmd/pub-get
 [`dart pub outdated`]: /tools/pub/cmd/pub-outdated
 [`dart pub upgrade`]: /tools/pub/cmd/pub-upgrade
diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md
index e284476f4d..8598249efe 100644
--- a/src/content/tools/pub/glossary.md
+++ b/src/content/tools/pub/glossary.md
@@ -7,7 +7,7 @@ The following terms are used in the documentation for
 [package management][] and
 the [pub tool][].
 
-[package management]: /guides/packages
+[package management]: /tools/pub/packages
 [pub tool]: /tools/pub/cmd
 
 ## Application package
diff --git a/src/content/tools/pub/package-layout.md b/src/content/tools/pub/package-layout.md
index cb8d2ac5d7..d9faa2181e 100644
--- a/src/content/tools/pub/package-layout.md
+++ b/src/content/tools/pub/package-layout.md
@@ -5,7 +5,7 @@ description: >-
   Dart's package management tool, pub.
 ---
 
-When you build a [pub package](/guides/packages),
+When you build a [pub package](/tools/pub/packages),
 we encourage you to follow the conventions that this page describes.
 They describe how you organize the files and directories within your
 package, and how to name things.
diff --git a/src/content/guides/packages.md b/src/content/tools/pub/packages.md
similarity index 100%
rename from src/content/guides/packages.md
rename to src/content/tools/pub/packages.md
diff --git a/src/content/tools/pub/publishing.md b/src/content/tools/pub/publishing.md
index 2fa2fefae2..fb5d270758 100644
--- a/src/content/tools/pub/publishing.md
+++ b/src/content/tools/pub/publishing.md
@@ -527,7 +527,7 @@ If you change your mind, you can remove the discontinued mark at any time.
 [Markdown]: {{site.pub-pkg}}/markdown
 [pkg-layout]: /tools/pub/package-layout
 [policy]: {{site.pub}}/policy
-[pub]: /guides/packages
+[pub]: /tools/pub/packages
 [`dart pub publish`]: /tools/pub/cmd/pub-lish
 [pubspec]: /tools/pub/pubspec
 [semver]: https://semver.org/spec/v2.0.0-rc.1.html
diff --git a/src/content/tools/pub/pubspec.md b/src/content/tools/pub/pubspec.md
index c15292ed79..61e446b1e5 100644
--- a/src/content/tools/pub/pubspec.md
+++ b/src/content/tools/pub/pubspec.md
@@ -3,7 +3,7 @@ title: The pubspec file
 description: Reference guide for the fields in pubspec.yaml.
 ---
 
-Every [pub package](/guides/packages) needs some metadata so it can specify its
+Every [pub package](/tools/pub/packages) needs some metadata so it can specify its
 [dependencies](/tools/pub/glossary#dependency). Pub packages that are shared with
 others also need to provide some other information so users can discover them.
 All of this metadata goes in the package's _pubspec:_
diff --git a/src/content/tools/pub/versioning.md b/src/content/tools/pub/versioning.md
index 85a1eab1aa..c6d8757d28 100644
--- a/src/content/tools/pub/versioning.md
+++ b/src/content/tools/pub/versioning.md
@@ -463,7 +463,7 @@ consult the [PubGrub][pubgrub] article on Medium.
 
 [immediate-dep]: /tools/pub/glossary#immediate-dependency
 [transitive-dep]: /tools/pub/glossary#transitive-dependency
-[pub]: /guides/packages
+[pub]: /tools/pub/packages
 [npm]: https://npmjs.org/
 [bundler]: https://bundler.io
 [caret-syntax]: /tools/pub/dependencies#caret-syntax
diff --git a/src/content/tutorials/index.md b/src/content/tutorials/index.md
index 4d3eef1e34..f49cdb2a3a 100644
--- a/src/content/tutorials/index.md
+++ b/src/content/tutorials/index.md
@@ -24,7 +24,7 @@ which are fundamental to most Dart programs.
     <p>Use streams to manage sequences of data.</p>
   </div>
   <div class="card">
-    <h3><a href="/guides/packages">How to use packages</a></h3>
+    <h3><a href="/tools/pub/packages">How to use packages</a></h3>
     <p>Organize and share code at the
        <a href="{{site.pub}}">pub.dev site.</a></p>
   </div>
diff --git a/src/content/tutorials/server/cmdline.md b/src/content/tutorials/server/cmdline.md
index 2a91979f09..db8ae40035 100644
--- a/src/content/tutorials/server/cmdline.md
+++ b/src/content/tutorials/server/cmdline.md
@@ -141,7 +141,7 @@ Future<void> _handleError(String path) async {
 
 You might notice that dcat depends on a package named **args**.
 To get the args package, use the
-[pub package manager](/guides/packages).
+[pub package manager](/tools/pub/packages).
 
 A real app has tests, license files, dependency files, examples, and so on.
 For the first app though, we can easily create only what is necessary
@@ -172,7 +172,7 @@ with the [`dart create`](/tools/dart-create) command.
 
 :::note
 To learn more about using packages and organizing your code, check out
-[How to use packages](/guides/packages) and
+[How to use packages](/tools/pub/packages) and
 [Package layout conventions](/tools/pub/package-layout).
 :::
 
diff --git a/src/content/tutorials/server/get-started.md b/src/content/tutorials/server/get-started.md
index 525e2a36ca..0d7b36796b 100644
--- a/src/content/tutorials/server/get-started.md
+++ b/src/content/tutorials/server/get-started.md
@@ -63,7 +63,7 @@ This command creates a small Dart app that has the following:
 * An additional Dart file, `lib/cli.dart`, that contains the functionality of
   the app and is imported by the `cli.dart` file.
 * A pubspec file, `pubspec.yaml`, that contains the app's metadata, including
-  information about which [packages](/guides/packages) the app depends on
+  information about which [packages](/tools/pub/packages) the app depends on
   and which versions of those packages are required.
 
 :::note