From 220bccb9d7676aaf10ad51b6e4a483cbdb577a81 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Tue, 10 Dec 2024 12:11:05 +0530 Subject: [PATCH] Move package related docs out of `/guides` directory (#6260) Not all of the content in the [Creating packages](https://dart.dev/guides/libraries/create-packages) page belongs in the pub docs, but that's where we include it now anyway. Some of it is about libraries (imports, exports, conditional exports, etc.). I'll create separate issues to solve that mix of concerns, but for now this starts to clean up the `/guides` directory. Contributes to https://github.com/dart-lang/site-www/issues/5767 --- firebase.json | 14 ++++++++------ src/_data/glossary.yml | 4 ++-- src/_data/keywords.yml | 6 +++--- src/_data/side-nav.yml | 4 ++-- src/content/guides/language/evolution.md | 2 +- src/content/language/libraries.md | 2 +- src/content/resources/coming-from/js-to-dart.md | 4 ++-- src/content/resources/coming-from/swift-to-dart.md | 2 +- src/content/resources/whats-new.md | 2 +- src/content/tools/dart-run.md | 2 +- src/content/tools/pub/cmd/pub-get.md | 2 +- .../libraries => tools/pub}/create-packages.md | 4 ++-- src/content/tools/pub/package-layout.md | 2 +- src/content/tools/pub/packages.md | 4 ++-- .../libraries => tools/pub}/private-files.md | 6 ++++-- 15 files changed, 32 insertions(+), 28 deletions(-) rename src/content/{guides/libraries => tools/pub}/create-packages.md (99%) rename src/content/{guides/libraries => tools/pub}/private-files.md (94%) diff --git a/firebase.json b/firebase.json index 8f754b1998..be666ed0b2 100644 --- a/firebase.json +++ b/firebase.json @@ -229,11 +229,13 @@ { "source": "/guides/language/specifications/DartLangSpec-v2.2.pdf", "destination": "https://github.com/dart-lang/site-www/blob/a7f170389e210adc2aef810cc9a6fdbfa78059a5/src/guides/language/specifications/DartLangSpec-v2.2.pdf", "type": 301 }, { "source": "/guides/language/type-system", "destination": "/language/type-system", "type": 301 }, { "source": "/guides/libraries", "destination": "/libraries", "type": 301 }, - { "source": "/guides/libraries/create-library-packages", "destination": "/guides/libraries/create-packages", "type": 301 }, + { "source": "/guides/libraries/create-library-packages", "destination": "/tools/pub/create-packages", "type": 301 }, + { "source": "/guides/libraries/create-packages", "destination": "/tools/pub/create-packages", "type": 301 }, { "source": "/guides/libraries/futures-error-handling", "destination": "/libraries/async/futures-error-handling", "type": 301 }, { "source": "/guides/libraries/java-interop", "destination": "/interop/java-interop", "type": 301 }, { "source": "/guides/libraries/objective-c-interop", "destination": "/interop/objective-c-interop", "type": 301 }, { "source": "/guides/libraries/c-interop", "destination": "/interop/c-interop", "type": 301 }, + { "source": "/guides/libraries/private-files", "destination": "/tools/pub/private-files", "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 }, @@ -265,7 +267,7 @@ { "source": "/keyword/dynamic", "destination": "/effective-dart/design#avoid-using-dynamic-unless-you-want-to-disable-static-checking", "type": 301 }, { "source": "/keyword/else", "destination": "/language/branches#if", "type": 301 }, { "source": "/keyword/enum", "destination": "/language/enums", "type": 301 }, - { "source": "/keyword/export", "destination": "/guides/libraries/create-packages", "type": 301 }, + { "source": "/keyword/export", "destination": "/tools/pub/create-packages", "type": 301 }, { "source": "/keyword/extends", "destination": "/language/extend", "type": 301 }, { "source": "/keyword/extension", "destination": "/language/extension-methods", "type": 301 }, { "source": "/keyword/extension-type", "destination": "/language/extension-types", "type": 301 }, @@ -291,10 +293,10 @@ { "source": "/keyword/mixin", "destination": "/language/mixins", "type": 301 }, { "source": "/keyword/new", "destination": "/language/classes#using-constructors", "type": 301 }, { "source": "/keyword/null", "destination": "/language/variables#default-value", "type": 301 }, - { "source": "/keyword/of", "destination": "/guides/libraries/create-packages#organizing-a-package", "type": 301 }, + { "source": "/keyword/of", "destination": "/tools/pub/create-packages#organizing-a-package", "type": 301 }, { "source": "/keyword/on", "destination": "/language/error-handling#catch", "type": 301 }, { "source": "/keyword/operator", "destination": "/language/methods#operators", "type": 301 }, - { "source": "/keyword/part", "destination": "/guides/libraries/create-packages#organizing-a-package", "type": 301 }, + { "source": "/keyword/part", "destination": "/tools/pub/create-packages#organizing-a-package", "type": 301 }, { "source": "/keyword/required", "destination": "/language/functions#named-parameters", "type": 301 }, { "source": "/keyword/rethrow", "destination": "/language/error-handling#catch", "type": 301 }, { "source": "/keyword/return", "destination": "/language/functions#return-values", "type": 301 }, @@ -367,7 +369,6 @@ { "source": "/to/web-debug-extension", "destination": "https://chromewebstore.google.com/detail/dart-debug-extension/eljbmlghnomdjgdjmbdekegdkbabckhm", "type": 301 }, { "source": "/tools/**/download{,.html,/**}", "destination": "/get-dart", "type": 301 }, - { "source": "/tools/**/private-files", "destination": "/guides/libraries/private-files", "type": 301 }, { "source": "/tools/analyzer", "destination": "/tools/dart-analyze", "type": 301 }, { "source": "/tools/dart-pub", "destination": "/tools/pub/cmd", "type": 301 }, { "source": "/tools/dart-vm", "destination": "/tools/dart-run", "type": 301 }, @@ -389,12 +390,13 @@ { "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/private-files", "destination": "/tools/pub/private-files", "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 }, { "source": "/tools/pub/cmd/pub-serve", "destination": "/tools/webdev", "type": 301 }, { "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/create-library-packages", "destination": "/tools/pub/create-packages", "type": 301 }, { "source": "/tools/pub/faq", "destination": "/tools/faq#pub", "type": 301 }, { "source": "/tools/pub/get-started", "destination": "/tools/pub/packages", "type": 301 }, { "source": "/tools/pub/installing", "destination": "/tools/pub/environment-variables", "type": 301 }, diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml index 56dcd9bedc..b2dfc3256c 100644 --- a/src/_data/glossary.yml +++ b/src/_data/glossary.yml @@ -334,7 +334,7 @@ and is included in a library using the `part` directive. related_links: - text: "Guidance on libraries and parts" - link: "/guides/libraries/create-packages#organizing-a-package" + link: "/tools/pub/create-packages#organizing-a-package" - text: "Use library URIs in `part of` directives" link: "/effective-dart/usage#do-use-strings-in-part-of-directives" labels: @@ -382,7 +382,7 @@ directory but not inside the `lib/src` directory. related_links: - text: "Organizing a package's libraries" - link: "/guides/libraries/create-packages#organizing-a-package" + link: "/tools/pub/create-packages#organizing-a-package" - text: "Public package directories" link: "/tools/pub/package-layout#public-directories" labels: diff --git a/src/_data/keywords.yml b/src/_data/keywords.yml index 3b648dd5d7..495b7ac181 100644 --- a/src/_data/keywords.yml +++ b/src/_data/keywords.yml @@ -56,7 +56,7 @@ link: /language/enums type: reserved - term: 'export' - link: /guides/libraries/create-packages + link: /tools/pub/create-packages type: bit - term: 'extends' link: /language/extend @@ -128,7 +128,7 @@ link: /language/variables#default-value type: reserved - term: 'of' - link: /guides/libraries/create-packages#organizing-a-package + link: /tools/pub/create-packages#organizing-a-package type: unrestricted - term: 'on' link: /language/error-handling#catch @@ -137,7 +137,7 @@ link: /language/methods#operators type: bit - term: 'part' - link: /guides/libraries/create-packages#organizing-a-package + link: /tools/pub/create-packages#organizing-a-package type: bit - term: 'required' link: /language/functions#named-parameters diff --git a/src/_data/side-nav.yml b/src/_data/side-nav.yml index 307534f364..860b9183e0 100644 --- a/src/_data/side-nav.yml +++ b/src/_data/side-nav.yml @@ -158,7 +158,7 @@ - title: Commonly used packages permalink: /resources/useful-packages - title: Creating packages - permalink: /guides/libraries/create-packages + permalink: /tools/pub/create-packages - title: Publishing packages permalink: /tools/pub/publishing - title: Writing package pages @@ -187,7 +187,7 @@ - title: Custom package repositories permalink: /tools/pub/custom-package-repositories - title: What not to commit - permalink: /guides/libraries/private-files + permalink: /tools/pub/private-files - title: Development expanded: false diff --git a/src/content/guides/language/evolution.md b/src/content/guides/language/evolution.md index 5887d9ef67..b67a255043 100644 --- a/src/content/guides/language/evolution.md +++ b/src/content/guides/language/evolution.md @@ -616,7 +616,7 @@ check out the [language versioning specification][]. [calling native C code]: /interop/c-interop [collection for]: /language/collections#control-flow-operators [collection if]: /language/collections#control-flow-operators -[Dart library]: /guides/libraries/create-packages#organizing-a-package +[Dart library]: /tools/pub/create-packages#organizing-a-package [Dart FFI]: /interop/c-interop [extension methods]: /language/extension-methods [Extension types]: /language/extension-types diff --git a/src/content/language/libraries.md b/src/content/language/libraries.md index a87a716663..897dcd415a 100644 --- a/src/content/language/libraries.md +++ b/src/content/language/libraries.md @@ -164,7 +164,7 @@ library; ## Implementing libraries See -[Create Packages](/guides/libraries/create-packages) +[Create Packages](/tools/pub/create-packages) for advice on how to implement a package, including: * How to organize library source code. diff --git a/src/content/resources/coming-from/js-to-dart.md b/src/content/resources/coming-from/js-to-dart.md index a36609720b..2f5d267530 100644 --- a/src/content/resources/coming-from/js-to-dart.md +++ b/src/content/resources/coming-from/js-to-dart.md @@ -2575,14 +2575,14 @@ By default, Dart limits access to private class members to code in the same file To expand the scope of a library beyond one file, add the `part` directive. When possible, [avoid using `part`][]. Reserve using `part` for code generators. -[avoid using `part`]: /guides/libraries/create-packages#organizing-a-package +[avoid using `part`]: /tools/pub/create-packages#organizing-a-package ### Late variables To indicate that Dart initializes class fields at a later point, assign the `late` keyword to those class fields. Those class fields remain non-nullable. -Do this when a variable doesn't need to observed or accessed immediately +Do this when a variable doesn't need to be observed or accessed immediately and can be initialized later. This differs from labeling the field as nullable. diff --git a/src/content/resources/coming-from/swift-to-dart.md b/src/content/resources/coming-from/swift-to-dart.md index b30a447e37..e560df6f05 100644 --- a/src/content/resources/coming-from/swift-to-dart.md +++ b/src/content/resources/coming-from/swift-to-dart.md @@ -2814,7 +2814,7 @@ class Parrot extends _Animal { For more information, check out [creating packages][]. -[creating packages]: /guides/libraries/create-packages#organizing-a-package +[creating packages]: /tools/pub/create-packages#organizing-a-package ## Next steps diff --git a/src/content/resources/whats-new.md b/src/content/resources/whats-new.md index 8ad8c2c3b7..56204ae5c4 100644 --- a/src/content/resources/whats-new.md +++ b/src/content/resources/whats-new.md @@ -549,7 +549,7 @@ we made the following changes to this site: [Objective-C and Swift interop]: /interop/objective-c-interop [Fixing common type problems]: /guides/language/sound-problems -[What not to commit]: /guides/libraries/private-files +[What not to commit]: /tools/pub/private-files [`dart pub get` Options]: /tools/pub/cmd/pub-get#options [`dart compile`]: /tools/dart-compile [Debugging Dart web apps]: /web/debugging diff --git a/src/content/tools/dart-run.md b/src/content/tools/dart-run.md index cefdc7c210..0700874127 100644 --- a/src/content/tools/dart-run.md +++ b/src/content/tools/dart-run.md @@ -40,7 +40,7 @@ you're executing the `dart run` command from the directory that's at the top of a Dart package (the _current package_). For information on the directory structure of Dart packages, see -[package layout conventions](/guides/libraries/create-packages). +[package layout conventions](/tools/pub/create-packages). ### In a depended-on package diff --git a/src/content/tools/pub/cmd/pub-get.md b/src/content/tools/pub/cmd/pub-get.md index 2b9f6dbf13..100094898d 100644 --- a/src/content/tools/pub/cmd/pub-get.md +++ b/src/content/tools/pub/cmd/pub-get.md @@ -65,7 +65,7 @@ in the `.dart_tool/` directory that maps from package names to location URIs. Don't check the generated `.dart_tool/` directory into your repo; add it to your repo's `.gitignore` file. For more information, -see [What not to commit](/guides/libraries/private-files). +see [What not to commit](/tools/pub/private-files). ::: diff --git a/src/content/guides/libraries/create-packages.md b/src/content/tools/pub/create-packages.md similarity index 99% rename from src/content/guides/libraries/create-packages.md rename to src/content/tools/pub/create-packages.md index 40a5bd2385..5efa921026 100644 --- a/src/content/guides/libraries/create-packages.md +++ b/src/content/tools/pub/create-packages.md @@ -305,8 +305,8 @@ Use the following resources to learn more about packages: using library files. * 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. +* [What not to commit](/tools/pub/private-files) + covers what shouldn't be checked into a source code repository. * The newer packages under the [dart-lang]({{site.repo.dart.org}}) organization tend to show best practices. Consider studying these examples: diff --git a/src/content/tools/pub/package-layout.md b/src/content/tools/pub/package-layout.md index d9faa2181e..045c96d324 100644 --- a/src/content/tools/pub/package-layout.md +++ b/src/content/tools/pub/package-layout.md @@ -246,7 +246,7 @@ Also, avoid imports of package:package_name/src/.... ::: For more information on packages, see -[Creating packages](/guides/libraries/create-packages). +[Creating packages](/tools/pub/create-packages). ### Public tools diff --git a/src/content/tools/pub/packages.md b/src/content/tools/pub/packages.md index 55481448cd..aa049e45bb 100644 --- a/src/content/tools/pub/packages.md +++ b/src/content/tools/pub/packages.md @@ -147,7 +147,7 @@ that your package uses. If your package is an [application package](/tools/pub/glossary#application-package) you should check this file into -[source control](/guides/libraries/private-files). +[source control](/tools/pub/private-files). That way, everyone working on your app uses the same versions of all of its dependencies. Checking in the lockfile also ensures that your deployed app @@ -269,7 +269,7 @@ the pub package manager. ### How to -* [Creating packages](/guides/libraries/create-packages) +* [Creating packages](/tools/pub/create-packages) * [Publishing packages](/tools/pub/publishing) ### Reference diff --git a/src/content/guides/libraries/private-files.md b/src/content/tools/pub/private-files.md similarity index 94% rename from src/content/guides/libraries/private-files.md rename to src/content/tools/pub/private-files.md index 5a11c1c08b..5ba0273f36 100644 --- a/src/content/guides/libraries/private-files.md +++ b/src/content/tools/pub/private-files.md @@ -1,10 +1,12 @@ --- title: What not to commit -description: Your development tools generate a bunch of files. Not all of them should be committed. +description: >- + Your development tools generate a bunch of files. + Not all of them should be committed. --- When you put Dart source code in a repository—using the -[pub tool](/tools/pub/cmd), [GitHub,](https://github.com/) +[pub tool](/tools/pub/cmd), [GitHub](https://github.com/), or another source code management system—don't include most of the files that your IDE or code editor, the pub tool, and other tools generate.