app/views/doc/versioning.html - Issue 162403002: Remove docs and point to ones on dartlang.org.

Unified Diff: app/views/doc/versioning.html

Issue 162403002: Remove docs and point to ones on dartlang.org. (Closed) Base URL: https://github.com/dart-lang/pub-dartlang.git@master

Patch Set: Re-upload. Created 6 years, 10 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

Index: app/views/doc/versioning.html

diff --git a/app/views/doc/versioning.html b/app/views/doc/versioning.html

deleted file mode 100644

index 76c8b93a0531e7d2bb17dd4f9c54ebcd0882a5f5..0000000000000000000000000000000000000000

--- a/app/views/doc/versioning.html

+++ /dev/null

@@ -1,372 +0,0 @@

-<ol class="toc">

- <li><a href="#a-name-and-a-number">A name and a number</a></li>

- <li><a href="#shared-dependencies-and-unshared-libraries">Shared dependencies and unshared libraries</a></li>

- <li><a href="#version-lock">Version lock</a></li>

- <li><a href="#version-constraints">Version constraints</a></li>

- <li><a href="#semantic-versions">Semantic versions</a></li>

- <li><a href="#constraint-solving">Constraint solving</a></li>

- <li><a href="#constraint-context">Constraint context</a></li>

- <li><a href="#lockfiles">Lockfiles</a></li>

- <li><a href="#when-things-go-wrong">When things go wrong</a></li>

- <li><a href="#summary">Summary</a></li>

-</ol>

-One of pub’s main jobs is helping you work with versioning. Here, I’ll

-explain a bit about the history of versioning and pub’s approach to it.

-Consider this to be advanced information. If you want a better picture of why

-pub was designed the way it was, read on. If you just want to use pub, the

-<a href="index.html">other docs</a> will serve you better.

-Modern software development, especially web development, leans heavily on

-reusing lots and lots of existing code. That includes code you wrote in the

-past, but also stuff from third-parties, everything from big frameworks to tiny

-little utility libraries. It’s not uncommon for an application to depend on

-dozens of different packages and libraries.

-It’s hard to understate how awesome this is. When you see stories of tiny web

-startups building a site in a few weeks that gets millions of users, the

-only reason they can pull that off is because the open source community has

-laid a feast of software at their feet.

-But there’s still no such thing as a free lunch. There’s a challenge to code

-reuse, especially reusing code you don’t maintain. When your app uses tons of

-code being developed by other people, what happens when they change it? They

-don’t want to break your app, and you certainly don’t either.

-<h2 id="a-name-and-a-number">A name and a number</h2>

-We solve this by versioning. When you depend on some piece of outside code,

-you don’t just say “My app uses <code>widgets</code>.” You say, “My app uses

-<code>widgets 2.0.5</code>.” That combination of name and version number uniquely

-identifies an immutable chunk of code. The people hacking on <code>widgets</code> can

-make all of the changes they want, but they promise to not touch any already

-released versions. They can put out <code>2.0.6</code> or <code>3.0.0</code> and it won’t affect you

-one whit because the version you use is unchanged.

-When you do want to get those changes, you can always point your app to a

-newer version of <code>widgets</code> and you don’t have to coordinate with those

-developers to do it. So, problem solved, right?

-<h2 id="shared-dependencies-and-unshared-libraries">Shared dependencies and unshared libraries</h2>

-Well, no. Depending on specific versions works fine when your dependency graph

-is really just a dependency tree. If your app depends on a bunch of stuff, and

-those things in turn have their own dependencies and so on, that all works fine

-as long as none of those dependencies overlap.

-But let’s consider an example:

-<pre><code> myapp

- / \

-widgets templates

- \ /

- collections

-</code></pre>

-So your app uses <code>widgets</code> and <code>templates</code>, and both of those use

-<code>collections</code>. This is called a shared dependency. Now what happens when

-<code>widgets</code> wants to use <code>collections 2.3.5</code> and <code>templates</code> wants

-<code>collections 2.3.7</code>? What if they don’t agree on a version?

-One option is to just let the app use both

-versions of <code>collections</code>. It will have two copies of the library at different

-versions and <code>widgets</code> and <code>templates</code> will each get the one they want.

-This is what <a href="https://npmjs.org/">npm</a> does for node.js. Would it work for Dart? Consider this

-scenario:

-<ol>

- <li><code>collections</code> defines some <code>Dictionary</code> class.</li>

- <li><code>widgets</code> gets an instance of it from its copy of <code>collections</code> (<code>2.3.5</code>).

-It then passes it up to <code>myapp</code>.</li>

- <li><code>myapp</code> sends the dictionary over to <code>templates</code>.</li>

- <li>That in turn sends it down to its version of <code>collections</code> (<code>2.3.7</code>).</li>

- <li>The method that takes it has a <code>Dictionary</code> type annotation for that object.</li>

-</ol>

-As far as Dart is concerned, <code>collections 2.3.5</code> and <code>collections 2.3.7</code> are

-entirely unrelated libraries. If you take an instance of class <code>Dictionary</code> from

-one and pass it to a method in the other, that’s a completely different

-<code>Dictionary</code> type. That means it will fail to match a <code>Dictionary</code> type

-annotation in the receiving library. Oops.

-Because of this (and because of the headaches of trying to debug an app that

-has multiple versions of things with the same name), we’ve decided npm’s model

-isn’t a good fit.

-<h2 id="version-lock">Version lock</h2>

-Instead, when you depend on a package, your app will only use a single copy of

-that package. When you have a shared dependency, everything that depends on it

-has to agree on which version to use. If they don’t, you get an error.

-That doesn’t actually solve your problem though. When you do get that error,

-you need to be able to resolve it. So let’s say you’ve gotten yourself into

-that situation in the above example. You want to use <code>widgets</code> and <code>templates</code>,

-but they are using different versions of <code>collections</code>. What do you do?

-The answer is to try to upgrade one of those. <code>templates</code> wants

-<code>collections 2.3.7</code>. Is there a later version of <code>widgets</code> that you can upgrade

-to that works with that version?

-In many cases, the answer will be “no”. Look at it from the perspective of the

-people developing <code>widgets</code>. They want to put out a new version with new changes

-to their code, and they want as many people to be able to upgrade to it it as

-possible. If they stick to their current version of <code>collections</code> then anyone

-who is using the current version <code>widgets</code> will be able to drop in this new one

-too.

-If they were to upgrade their dependency on <code>collections</code> then everyone who

-upgrades <code>widgets</code> would have to as well, whether they want to or not. That’s

-painful, so you end up with a disincentive to upgrade dependencies. That’s

-called version lock: everyone wants to move their dependencies forward, but

-no one can take the first step because it forces everyone else to as well.

-<h2 id="version-constraints">Version constraints</h2>

-To solve version lock, we loosen the constraints that packages place on their

-dependencies. If <code>widgets</code> and <code>templates</code> can both indicate a range of

-versions for <code>collections</code> that they will work with, then that gives us enough

-wiggle room to move our dependencies forward to newer versions. As long as there

-is overlap in their ranges, we can still find a single version that makes them

-both happy.

-This is the model that <a href="http://gembundler.com/">bundler</a> follows, and is pub’s

-model too. When you add a dependency in your pubspec, you can specify a range

-of versions that you can accept. If the pubspec for <code>widgets</code> looked like this:

-<div class="highlight"><pre><code class="yaml">dependencies:

- collections: '>=2.3.5 <2.4.0'

-</code></pre></div>

-Then we could pick version <code>2.3.7</code> for <code>collections</code> and then both <code>widgets</code>

-and <code>templates</code> have their constraints satisfied by a single concrete version.

-<h2 id="semantic-versions">Semantic versions</h2>

-When you add a dependency to your package, you’ll sometimes want to specify a

-range of versions to allow. How do you know what range to pick? You need to

-forward compatible, so ideally the range encompasses future versions that

-haven’t been released yet. But how do you know your package is going to work

-with some new version that doesn’t even exist yet?

-To solve that, you need to agree on what a version number means. Imagine that

-the developers of a package you depend on say, “If we make any backwards

-incompatible change, then we promise to increment the major version number.”

-If you trust them, then if you know your package works with <code>2.5.7</code> of theirs,

-you can rely on it working all the way up to <code>3.0.0</code>. So you can set your range

-like:

-<div class="highlight"><pre><code class="yaml">dependencies:

- collections: '>=2.3.5 <3.0.0'

-</code></pre></div>

-To make this work, then, we need to come up with that set of promises.

-Fortunately, other smart people have done the work of figuring this all out and

-named it <a href="http://semver.org/">semantic versioning</a>.

-That describes the format of a version number, and the exact API behavioral

-differences when you increment to a later version number. Pub requires versions

-to be formatted that way, and to play well with the pub community, your package

-should follow the semantics it specifies. You should assume that the packages

-you depend on also follow it. (And if you find out they don’t, let their

-authors know!)

-We’ve got almost all of the pieces we need to deal with versioning and API

-evolution now. Let’s see how they play together and what pub does.

-<h2 id="constraint-solving">Constraint solving</h2>

-When you define your package, you list its

-<a href="glossary.html#immediate-dependency">immediate dependencies</a>—the

-packages it itself uses. For each one, you specify the range of versions it

-allows. Each of those dependent packages may in turn have their own

-dependencies (called

-<a href="glossary.html#transitive-dependency">transitive dependencies</a>. Pub will

-traverse these and build up the entire deep dependency graph for your app.

-For each package in the graph, pub looks at everything that depends on it. It

-gathers together all of their version constraints and tries to simultaneously

-solve them. (Basically, it intersects their ranges.) Then it looks at the

-actual versions that have been released for that package and selects the best

-(most recent) one that meets all of those constraints.

-For example, let’s say our dependency graph contains <code>collections</code>, and three

-packages depend on it. Their version constraints are:

-<pre><code>>=1.7.0

->=1.4.0 <2.0.0

-<1.9.0

-</code></pre>

-The developers of <code>collections</code> have released these versions of it:

-<pre><code>1.7.0

-1.7.1

-1.8.0

-1.8.1

-1.8.2

-1.9.0

-</code></pre>

-The highest version number that fits in all of those ranges is <code>1.8.2</code>, so pub

-picks that. That means your app and every package your app uses will all use

-<code>collections 1.8.2</code>.

-<h2 id="constraint-context">Constraint context</h2>

-The fact that selecting a package version takes into account every package

-that depends on it has an important consequence: the specific version that

-will be selected for a package is a global property of the app using that

-package.

-I’ll walk through an example so you can see what this means. Let’s say we have

-two apps. Here are their pubspecs:

-<div class="highlight"><pre><code class="yaml">name: my_app

-dependencies:

- widgets:

-</code></pre></div>

-<div class="highlight"><pre><code class="yaml">name: other_app

-dependencies:

- widgets:

- collections: '<1.5.0'

-</code></pre></div>

-They both depend on <code>widgets</code>, whose pubspec is:

-<div class="highlight"><pre><code class="yaml">name: widgets

-dependencies:

- collections: '>=1.0.0 <2.0.0'

-</code></pre></div>

-The <code>other_app</code> package uses depends directly on <code>collections</code> itself. The

-interesting part is that it happens to have a different version constraint on

-it than <code>widgets</code> does.

-What this means is that you can’t just look at the <code>widgets</code> package in

-isolation to figure out what version of <code>collections</code> it will use. It depends

-on the context. In <code>my_app</code>, <code>widgets</code> will be using <code>collections 1.9.9</code>. But

-in <code>other_app</code>, <code>widgets</code> will get saddled with <code>collections 1.4.9</code> because of

-the other constraint that <code>otherapp</code> places on it.

-This is why each app gets its own “packages” directory: The concrete version

-selected for each package depends on the entire dependency graph of the

-containing app.

-<h2 id="lockfiles">Lockfiles</h2>

-So once pub has solved your app’s version constraints, then what? The end

-result is a complete list of every package that your app depends on either

-directly or indirectly and the best version of that package that will work with

-your app’s constraints.

-Pub takes that and writes it out to a lockfile in your app’s directory

-called <code>pubspec.lock</code>. When pub builds the “packages” directory your app, it

-uses the lockfile to know what versions of each package to pull in. (And if

-you’re curious to see what versions it selected, you can read the lockfile to

-find out.)

-The next important thing pub does is it stops touching the lockfile. Once

-you’ve got a lockfile for your app, pub won’t mess with it until you tell it to.

-This is important. It means you won’t spontanteously start using new versions

-of random packages in your app without intending to. Once your app is locked,

-it stays locked until you manually tell it to update the lockfile.

-If your package is for an app, you take your lockfile check that bad boy

-into your source control system! That way, everyone on your team will be using

-the exact same versions of every dependency when they hack on your app. You’ll

-also use this when you deploy your app so you can ensure that your production

-servers are using the exact same packages that you’re developing with.

-<h2 id="when-things-go-wrong">When things go wrong</h2>

-Of course, all of this presumes that your dependency graph is perfect and

-flawless. Oh, to be so fortunate. Even with version ranges and pub’s constraint

-solving and semantic versioning, you can never be entirely spared from the

-dangers of version hell.

-There are a couple of problems you can run into:

-<h3 id="you-can-have-disjoint-constraints">You can have disjoint constraints</h3>

-Lets say your app uses <code>widgets</code> and

-<code>templates</code> and both use <code>collections</code>. But <code>widgets</code> asks for a version

-of it between <code>1.0.0</code> and <code>2.0.0</code> and <code>templates</code> wants something

-between <code>3.0.0</code> and <code>4.0.0</code>. Those ranges don’t even overlap. There’s no

-possible version that would work.

-<h3 id="you-can-have-ranges-that-dont-contain-a-released-version">You can have ranges that don’t contain a released version</h3>

-Let’s say after

-putting all of the constraints on a shared dependency together, you’re

-left with the narrow range of <code>>=1.2.4 <1.2.6</code>. It’s not an empty range.

-If there was a version <code>1.2.4</code> of the dependency, you’d be golden. But maybe

-they never released that and instead when straight from <code>1.2.3</code> to <code>1.3.0</code>.

-You’ve got a range but nothing exists inside it.

-<h3 id="you-can-have-an-unstable-graph">You can have an unstable graph</h3>

-This is, by far, the hairiest part of

-pub’s version solving process. I’ve described the process as “build up the

-dependency graph and then solve all of the constraints and pick versions”.

-But it doesn’t actually work that way. How could you build up the whole

-dependency graph before you’ve picked any versions? The pubspecs

-themselves are version-specific. Different versions of the same package

-may have different sets of dependencies.

-As you’re selecting versions of packages, they are changing the shape of

-the dependency graph itself. As the graph changes, that may change

-constraints, which can cause you to select different versions, and then you

-go right back around in a circle.

-Sometimes this process never settles down into a stable solution. Gaze into

-the abyss:

-<div class="highlight"><pre><code class="yaml">name: my_app

-version: 0.0.0

-dependencies:

- yin: '>=1.0.0'

-</code></pre></div>

-<div class="highlight"><pre><code class="yaml">name: yin

-version: 1.0.0

-dependencies:

-</code></pre></div>

-<div class="highlight"><pre><code class="yaml">name: yin

-version: 2.0.0

-dependencies:

- yang: '1.0.0'

-</code></pre></div>

-<div class="highlight"><pre><code class="yaml">name: yang

-version: 1.0.0

-dependencies:

- yin: '1.0.0'

-</code></pre></div>

-In all of these cases, there is no set of concrete versions that will work for

-your app, and when this happens pub will report an error and tell you what’s

-going on. It definitely will not try to leave you in some weird state where you

-think things can work but won’t.

-<h2 id="summary">Summary</h2>

-Wow, that’s a lot to get through. Here’s the important bits:

-<ul>

- <li>Code reuse is great, but in order to let developers move quickly, packages

-need to be able to evolve independently.</li>

- <li>Versioning is how you enable that. But depending on single concrete versions

-is too precise and with shared dependencies leads to version lock.</li>

- <li>To cope with that, you depend on ranges of versions. Pub will then walk

-your dependency graph and pick the best versions for you. If it can’t, it

-tells you.</li>

- <li>Once your app has a solid set of versions for its dependencies, that gets

-pinned down in a lockfile. That ensures that every machine your app is

-on is using the same versions of all of its dependencies.</li>

-</ul>

« no previous file with comments | « app/views/doc/pubspec.html ('k') | app/views/index.mustache » ('j') | app/views/index.mustache » ('J')