From cc665190ca803d0352d370cc1b06935363813841 Mon Sep 17 00:00:00 2001 From: Parker Lougheed <parlough@gmail.com> Date: Mon, 28 Oct 2024 11:53:52 -0700 Subject: [PATCH 1/4] Begin adding pub glossary terms to shared glossary --- src/_data/glossary.yml | 285 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 285 insertions(+) diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml index 56dcd9bedc..ce3d7ee4f4 100644 --- a/src/_data/glossary.yml +++ b/src/_data/glossary.yml @@ -626,3 +626,288 @@ - "covariant" - "contravariance" - "contravariant" + +- term: "Version constraint" + short_description: |- + TODO + long_description: |- + A constraint placed on each [dependency][] of a package that specifies which + versions of that dependency the package is expected to work with. + This can be a single version (`0.3.0`) or a range of versions (`^1.2.1`). + While `any` is also allowed, + for performance reasons the Dart team doesn't recommend it. + + [Packages][] should always specify version constraints + for all of their dependencies. + [Application packages][], on the other hand, should usually + allow any version of their dependencies, since they use + the [lockfile][] to manage their dependency versions. + + [dependency]: #dependency + [Packages]: #package + [Application packages]: #application-package + [lockfile]: #lockfile + related_links: + - text: "Dart package version constraints" + link: "/tools/pub/dependencies#version-constraints" + - text: "Pub versioning philosophy" + link: "/tools/pub/versioning" + category: "packages" + labels: + - "versioning" + - "dependencies" + - "pubspec" + alternate: + - "dependency constraint" + +- term: "Verified publisher" + short_description: |- + TODO + long_description: |- + One or more users who own a set of packages. + Each verified publisher is identified by a verified domain name, + such as **dart.dev**. + related_links: + - text: "Verified publishers" + link: "/tools/pub/verified-publishers" + - text: "Creating a verified publisher" + link: "/tools/pub/publishing#verified-publisher" + - text: "List of verified publishers" + link: "TODO" + category: "packages" + labels: + - "publishing" + - "pub.dev" + +- term: "Uploader" + short_description: |- + TODO + long_description: |- + Someone who has administrative permissions for a package. + A package uploader can upload new versions of the package, + and they can also [add and remove other uploaders][] for that package. + + If a package has a verified publisher, + then all members of the publisher can upload the package. + + [add and remove other uploaders]: /tools/pub/publishing#uploaders + related_links: + - text: "Verified publishers" + link: "/tools/pub/verified-publishers" + - text: "Package publishing" + link: "TODO" + category: "packages" + labels: + - "publishing" + - "pub.dev" + +- term: "Transitive dependency" + short_description: |- + TODO + long_description: |- + A dependency that your package indirectly uses because + one of its dependencies requires it. + If your package depends on A, which in turn depends on B which + depends on C, then A is an [immediate dependency][] while + B and C are transitive ones. + + [immediate dependency]: #immediate-dependency + related_links: + - text: "Types of dependencies" + link: "TODO" + category: "packages" + labels: + - "versioning" + - "dependencies" + +- term: "Pub system cache" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "package config" + - "cache" + alternate: + - "system cache" + +- term: "Source" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "pubspec" + - "dependencies" + - "versioning" + alternate: + - "pub source" + +- term: "SDK constraint" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "pubspec" + - "sdk" + - "versioning" + alternate: + - "dart constraint" + - "flutter version constraint" + +- term: "Package" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "libraries" + - "dependencies" + alternate: + - "library package" + +- term: "Lockfile" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "libraries" + - "dependencies" + - "pubspec" + alternate: + - "pubspec.lock" + - "pub lock" + - "lock file" + +- term: "Library" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "language" + labels: + # TODO(parlough): Perhaps labels and categories should just be combined. + # This fits in the "language" and "packages" categories + - "packages" + - "imports" + alternate: + - "libraries" + +- term: "Immediate dependency" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "Types of dependencies" + link: "TODO" + category: "packages" + labels: + - "versioning" + - "dependencies" + alternate: + - "direct dependency" + +- term: "Entrypoint directory" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "tools" + labels: + - "packages" + - "bin" + alternate: + - "direct dependency" + +- term: "Entrypoint" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "tools" + labels: + - "packages" + - "bin" + alternate: + - "Entrypoint package" + - "Root package" + - "Runnable library" + +- term: "Dependency" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "dependencies" + - "package dependency" + - "libraries" + +- term: "Content hash" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "pubspec" + - "pubspec.lock" + - "dependencies" + alternate: + - "pub hash" + - "checksum" + +- term: "Application package" + short_description: |- + TODO + long_description: |- + TODO + related_links: + - text: "TODO" + link: "TODO" + category: "packages" + labels: + - "apps" + - "pubspec.lock" + alternate: + - "app package" + - "app" \ No newline at end of file From 58c34c80563bee8af46596ef876771b7b41a2266 Mon Sep 17 00:00:00 2001 From: Parker Lougheed <parlough@gmail.com> Date: Sun, 17 Nov 2024 18:44:56 +0800 Subject: [PATCH 2/4] Remove use of categories --- src/_data/glossary.yml | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml index ce3d7ee4f4..131a15e2a3 100644 --- a/src/_data/glossary.yml +++ b/src/_data/glossary.yml @@ -652,8 +652,8 @@ link: "/tools/pub/dependencies#version-constraints" - text: "Pub versioning philosophy" link: "/tools/pub/versioning" - category: "packages" labels: + - "packages" - "versioning" - "dependencies" - "pubspec" @@ -674,8 +674,8 @@ link: "/tools/pub/publishing#verified-publisher" - text: "List of verified publishers" link: "TODO" - category: "packages" labels: + - "packages" - "publishing" - "pub.dev" @@ -696,8 +696,8 @@ link: "/tools/pub/verified-publishers" - text: "Package publishing" link: "TODO" - category: "packages" labels: + - "packages" - "publishing" - "pub.dev" @@ -715,8 +715,8 @@ related_links: - text: "Types of dependencies" link: "TODO" - category: "packages" labels: + - "packages" - "versioning" - "dependencies" @@ -728,8 +728,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "package config" - "cache" alternate: @@ -743,8 +743,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "pubspec" - "dependencies" - "versioning" @@ -759,8 +759,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "pubspec" - "sdk" - "versioning" @@ -776,8 +776,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "libraries" - "dependencies" alternate: @@ -791,8 +791,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "libraries" - "dependencies" - "pubspec" @@ -809,10 +809,8 @@ related_links: - text: "TODO" link: "TODO" - category: "language" labels: - # TODO(parlough): Perhaps labels and categories should just be combined. - # This fits in the "language" and "packages" categories + - "language" - "packages" - "imports" alternate: @@ -826,8 +824,8 @@ related_links: - text: "Types of dependencies" link: "TODO" - category: "packages" labels: + - "packages" - "versioning" - "dependencies" alternate: @@ -841,9 +839,9 @@ related_links: - text: "TODO" link: "TODO" - category: "tools" labels: - "packages" + - "tools" - "bin" alternate: - "direct dependency" @@ -856,9 +854,9 @@ related_links: - text: "TODO" link: "TODO" - category: "tools" labels: - "packages" + - "tools" - "bin" alternate: - "Entrypoint package" @@ -873,8 +871,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "dependencies" - "package dependency" - "libraries" @@ -887,8 +885,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "pubspec" - "pubspec.lock" - "dependencies" @@ -904,8 +902,8 @@ related_links: - text: "TODO" link: "TODO" - category: "packages" labels: + - "packages" - "apps" - "pubspec.lock" alternate: From b571a7f5f5c718d78fadcbd6014d502f8cfa9233 Mon Sep 17 00:00:00 2001 From: Parker Lougheed <parlough@gmail.com> Date: Sun, 17 Nov 2024 19:00:23 +0800 Subject: [PATCH 3/4] Move pub glossary terms to shared glossary --- src/_data/glossary.yml | 356 ++++++++++++++++++++++++++++++++--------- 1 file changed, 278 insertions(+), 78 deletions(-) diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml index 131a15e2a3..812d6e6218 100644 --- a/src/_data/glossary.yml +++ b/src/_data/glossary.yml @@ -628,8 +628,8 @@ - "contravariant" - term: "Version constraint" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- A constraint placed on each [dependency][] of a package that specifies which versions of that dependency the package is expected to work with. @@ -662,8 +662,6 @@ - term: "Verified publisher" short_description: |- - TODO - long_description: |- One or more users who own a set of packages. Each verified publisher is identified by a verified domain name, such as **dart.dev**. @@ -672,16 +670,16 @@ link: "/tools/pub/verified-publishers" - text: "Creating a verified publisher" link: "/tools/pub/publishing#verified-publisher" - - text: "List of verified publishers" - link: "TODO" + - text: "Dart team publishers" + link: "/resources/dart-team-packages" labels: - "packages" - "publishing" - "pub.dev" - term: "Uploader" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- Someone who has administrative permissions for a package. A package uploader can upload new versions of the package, @@ -695,15 +693,15 @@ - text: "Verified publishers" link: "/tools/pub/verified-publishers" - text: "Package publishing" - link: "TODO" + link: "/tools/pub/publishing" labels: - "packages" - "publishing" - "pub.dev" - term: "Transitive dependency" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- A dependency that your package indirectly uses because one of its dependencies requires it. @@ -713,52 +711,85 @@ [immediate dependency]: #immediate-dependency related_links: - - text: "Types of dependencies" - link: "TODO" + - text: "Package dependencies" + link: "/tools/pub/dependencies" labels: - "packages" - "versioning" - "dependencies" - term: "Pub system cache" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO + When pub gets a remote package, + it downloads it into a single _system cache_ directory maintained by + pub. On Mac and Linux, this directory defaults to `~/.pub-cache`. + On Windows, the directory defaults to `%LOCALAPPDATA%\Pub\Cache`, + though its exact location may vary depending on the Windows version. + You can specify a different location using the + [`PUB_CACHE`][] environment variable. + + Once packages are in the system cache, + pub creates a `package_config.json` file that maps each package + used by your application to the corresponding package in the cache. + + You only have to download a given version of a package once + and can then reuse it in as many packages as you would like. + If you specify the `--offline` flag to use cached packages, + you can delete and regenerate your `package_config.json` + files without having to access the network. + + [`PUB_CACHE`]: /tools/pub/environment-variables related_links: - - text: "TODO" - link: "TODO" + - text: "The system package cache" + link: "/tools/pub/cmd/pub-get#the-system-package-cache" labels: - "packages" - "package config" - "cache" alternate: - - "system cache" + - "system package cache" -- term: "Source" - short_description: |- - TODO +- term: "Dependency source" +# short_description: |- +# TODO long_description: |- - TODO + A kind of place that pub can get packages from. A source isn't + a specific place like the pub.dev site or some specific Git URL. + Each source describes a general procedure for + accessing a package in some way. + For example, _git_ is one source. + The git source knows how to download packages given a Git URL. + Several different [supported sources][] are available. + + [supported sources]: /tools/pub/dependencies#dependency-sources related_links: - - text: "TODO" - link: "TODO" + - text: "Pub dependency source reference" + link: "/tools/pub/dependencies#dependency-sources" labels: - "packages" - "pubspec" - "dependencies" - "versioning" alternate: + - "package source" + - "dependency source" - "pub source" - term: "SDK constraint" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO + The declared versions of the Dart SDK itself that + a package declares that it supports. An SDK constraint is specified using + normal [version constraint](#version-constraint) syntax, but in a + special _environment_ section [in the pubspec][environment constraints]. + + [environment constraints]: /tools/pub/pubspec#sdk-constraints related_links: - - text: "TODO" - link: "TODO" + - text: "Pubspec SDK constraints" + link: "/tools/pub/pubspec#sdk-constraints" labels: - "packages" - "pubspec" @@ -769,13 +800,50 @@ - "flutter version constraint" - term: "Package" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO + A collection of [libraries] under a directory, + with a [pubspec.yaml] in the root of that directory. + + Packages can have [dependencies](#dependency) on other packages + *and* can be dependencies themselves. + A package's `/lib` directory contains the + [public libraries][] that other packages can import and use. + They can also include scripts to be run directly. + A package that is not intended to be depended on by other packages is an + [application package][]. + Shared packages are [published][] to pub.dev, + but you can also have non-published packages. + + Don't check the [lockfile][] of a package into source + control, since libraries should support a range of dependency versions. + The [version constraints][] of a package's + [immediate dependencies][] should be as wide as possible while still + ensuring that the dependencies will be compatible with the versions that + were tested against. + + Since [semantic versioning][] requires that libraries increment their + major version numbers for any backwards incompatible changes, + packages will usually require their dependencies' versions to be + greater than or equal to the versions that were tested and + less than the next major version. So if your library + depended on the (fictional) `transmogrify` package and you tested it at + version 1.2.1, your version constraint would be [`^1.2.1`][]. + + [libraries]: #library + [pubspec.yaml]: /tools/pub/pubspec + [public libraries]: /tools/pub/package-layout#public-libraries + [application package]: #application-package + [published]: /tools/pub/publishing + [lockfile]: #lockfile + [version constraints]: #version-constraint + [immediate dependencies]: #immediate-dependency + [semantic versioning]: https://semver.org/spec/v2.0.0-rc.1.html + [`^1.2.1`]: /tools/pub/dependencies#caret-syntax related_links: - - text: "TODO" - link: "TODO" + - text: "How to use packages" + link: "/guides/packages" labels: - "packages" - "libraries" @@ -784,13 +852,31 @@ - "library package" - term: "Lockfile" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO - related_links: - - text: "TODO" - link: "TODO" + A file named `pubspec.lock` that specifies the concrete versions and + other identifying information for every immediate and transitive dependency + a package relies on. + + Unlike the pubspec, which only lists immediate dependencies and + allows version ranges, the lockfile comprehensively pins down + the entire dependency graph to specific versions of packages. + A lockfile ensures that you can recreate the + exact configuration of packages used by an application. + + The lockfile is generated automatically for you by pub when you run + [`pub get`](/tools/pub/cmd/pub-get), + [`pub upgrade`](/tools/pub/cmd/pub-upgrade), + or [`pub downgrade`](/tools/pub/cmd/pub-downgrade). + Pub includes a [content hash][] for each package + to check against during future resolutions. + + If your package is an [application package][], you will + typically check this into source control. + For regular packages, you usually won't. + + [content hash]: #content-hashes labels: - "packages" - "libraries" @@ -803,12 +889,15 @@ - term: "Library" short_description: |- - TODO - long_description: |- - TODO + A library is a single compilation unit, made up of a single primary file and + any optional number of [parts][]. Libraries have their own private scope. + + [parts]: /resources/glossary#part-file +# long_description: |- +# TODO related_links: - - text: "TODO" - link: "TODO" + - text: "Libraries & imports" + link: "/language/libraries" labels: - "language" - "packages" @@ -818,12 +907,13 @@ - term: "Immediate dependency" short_description: |- - TODO - long_description: |- - TODO + A [dependency](#dependency) that your package directly uses itself. + The dependencies you list in your pubspec are + your package's immediate dependencies. All other dependencies are + [transitive dependencies](#transitive-dependency). related_links: - - text: "Types of dependencies" - link: "TODO" + - text: "Package dependencies" + link: "/tools/pub/dependencies" labels: - "packages" - "versioning" @@ -833,12 +923,16 @@ - term: "Entrypoint directory" short_description: |- - TODO + A directory inside your package that is allowed to contain Dart entrypoints. long_description: |- - TODO - related_links: - - text: "TODO" - link: "TODO" + A directory inside your package that is allowed to contain + [Dart entrypoints](#entrypoint). + + Pub has a list of these directories: `benchmark`, `bin`, `example`, + `test`, `tool`, and `web` (and `lib`, for [Flutter apps][]). + Any subdirectories of those (except `bin`) may also contain entrypoints. + + [Flutter apps]: https://docs.flutter.dev/packages-and-plugins/developing-packages labels: - "packages" - "tools" @@ -847,13 +941,25 @@ - "direct dependency" - term: "Entrypoint" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO - related_links: - - text: "TODO" - link: "TODO" + In the general context of Dart, an _entrypoint_ is + a Dart library that is directly invoked by a Dart implementation. + When you reference a Dart library in a `<script>` tag or + pass it as a command-line argument to the standalone Dart VM, + that library is the entrypoint. + In other words, it's usually the `.dart` file that contains `main()`. + + In the context of pub, an _entrypoint package_ or _root package_ is + the root of a dependency graph. It will usually be an application. + When you run your app, it's the entrypoint package. + Every other package it depends on will not be an entrypoint in that context. + + A package can be an entrypoint in some contexts and not in others. Say your + app uses a package `A`. When you run your app, `A` is not the entrypoint + package. However, if you go over to `A` and execute its tests, in that + context, it *is* the entrypoint since your app isn't involved. labels: - "packages" - "tools" @@ -864,13 +970,23 @@ - "Runnable library" - term: "Dependency" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO + Another package that your package relies on. + If your package wants to import code from some other package, + that package must be a dependency. + Dependencies are specified in your package's [pubspec][] and + described in [Package dependencies][]. + + To see the dependencies used by a package, use [`pub deps`][]. + + [pubspec]: /tools/pub/pubspec + [Package dependencies]: /tools/pub/dependencies + [`pub deps`]: /tools/pub/cmd/pub-deps related_links: - - text: "TODO" - link: "TODO" + - text: "Package dependencies" + link: "/tools/pub/dependencies" labels: - "packages" - "dependencies" @@ -878,13 +994,83 @@ - "libraries" - term: "Content hash" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO + The pub.dev repository maintains a sha256 hash of + each package version it hosts. + Pub clients can use this hash to + validate the integrity of downloaded packages, + and protect against changes on the repository. + + When `dart pub get` downloads a package, + it computes the hash of the downloaded archive. + The hash of each hosted dependency is stored with the + [resolution][] in the [lockfile][]. + + The pub client uses this content hash + to verify that running `dart pub get` again using the same lockfile, + potentially on a different computer, uses exactly the same packages. + + If the locked hash doesn't match what's currently in the pub cache, + pub redownloads the archive. If it still doesn't match, the lockfile + updates and a warning is printed. For example: + + ```plaintext + $ dart pub get + Resolving dependencies... + [!Cached version of foo-1.0.0 has wrong hash - redownloading.!] + ~ foo 1.0.0 (was 1.0.0) + [!The existing content-hash from pubspec.lock doesn't match contents for:!] + * foo-1.0.0 from "pub.dev" + This indicates one of: + * The content has changed on the server since you created the pubspec.lock. + * The pubspec.lock has been corrupted. + + [!The content-hashes in pubspec.lock has been updated.!] + + For more information see: + https://dart.dev/go/content-hashes + + Changed 1 dependency! + ``` + + The updated content hash will show up in your version control diff, + and should make you suspicious. + + To make a discrepancy become an error instead of a warning, use + [`dart pub get --enforce-lockfile`][]. + The `--enforce-lockfile` option causes resolution to fail if + pub can't find package archives with the same hashes, + without updating the lockfile. + + ```plaintext + $ dart pub get [!--enforce-lockfile!] + Resolving dependencies... + Cached version of foo-1.0.0 has wrong hash - redownloading. + ~ foo 1.0.0 (was 1.0.0) + The existing content-hash from pubspec.lock doesn't match contents for: + * foo-1.0.0 from "pub.dev" + + This indicates one of: + * The content has changed on the server since you created the pubspec.lock. + * The pubspec.lock has been corrupted. + + For more information see: + https://dart.dev/go/content-hashes + [!Would change 1 dependency.!] + [!Unable to satisfy `pubspec.yaml` using `pubspec.lock`.!] + + To update `pubspec.lock` run `dart pub get` without + `--enforce-lockfile`. + ``` + + [resolution]: /tools/pub/cmd/pub-get + [lockfile]: #lockfile + [`dart pub get --enforce-lockfile`]: /tools/pub/cmd/pub-get#enforce-lockfile related_links: - - text: "TODO" - link: "TODO" + - text: "Enforce lockfile option" + link: "/tools/pub/cmd/pub-get#enforce-lockfile" labels: - "packages" - "pubspec" @@ -895,13 +1081,27 @@ - "checksum" - term: "Application package" - short_description: |- - TODO +# short_description: |- +# TODO long_description: |- - TODO - related_links: - - text: "TODO" - link: "TODO" + A package that contains a program or app, with a [main entrypoint][]. + Meant to be run directly, either on the command line or in a browser. + + Application packages may have [dependencies][] on other packages, + but are never depended on themselves. + Unlike regular [packages][], they are not intended to be shared. + + Application packages should check their [lockfiles][] into source + control, so that everyone working on the application and every location the + application is deployed has a consistent set of dependencies. Because their + dependencies are constrained by the lockfile, application packages usually + specify `any` for their dependencies' [version constraints][]. + + [main entrypoint]: #entrypoint + [dependencies]: #dependency + [packages]: #package + [lockfiles]: #lockfile + [version constraints]: #version-constraint labels: - "packages" - "apps" From 7d5ed3a07c8fac04c42054e21036e626dc4029ae Mon Sep 17 00:00:00 2001 From: Parker Lougheed <parlough@gmail.com> Date: Sun, 17 Nov 2024 19:02:48 +0800 Subject: [PATCH 4/4] Fix content hashes link --- src/_data/glossary.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml index 812d6e6218..3f84895ee7 100644 --- a/src/_data/glossary.yml +++ b/src/_data/glossary.yml @@ -876,7 +876,7 @@ typically check this into source control. For regular packages, you usually won't. - [content hash]: #content-hashes + [content hash]: #content-hash labels: - "packages" - "libraries"