Make the crates.io docs about publishing only, not using

Try to make this flow a bit more and have sections based on what
situation you might find yourself in.

diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md
index 58d4a446d2c81d391b4880a32909dd309675213f..ad1289049b63fc7a790ee24a4917aebca5b6465d 100644 (file)
--- a/src/doc/crates-io.md
+++ b/src/doc/crates-io.md
@@ -1,14 +1,14 @@
-# Publishing crates
+% Publishing on crates.io
 
-Ok, now that we’ve got a crate which is using dependencies from crates.io,
-let’s publish it! Publishing a crate is when a specific version is uploaded to
-crates.io.
+Once you've got a library that you'd like to share with the world, it's time to
+publish it on [crates.io][crates-io]! Publishing a crate is when a specific
+version is uploaded to be hosted on crates.io.
 
 Take care when publishing a crate, because a publish is **permanent**. The
 version can never be overwritten, and the code cannot be deleted. There is no
 limit to the number of versions which can be published, however.
 
-## Acquiring an API token
+# Before your first publish
 
 First thing’s first, you’ll need an account on [crates.io][crates-io] to acquire
 an API token. To do so, [visit the home page][crates-io] and log in via a GitHub
@@ -25,6 +25,11 @@ This command will inform Cargo of your API token and store it locally in your
 with anyone else. If it leaks for any reason, you should regenerate it
 immediately.
 
+# Before publishing a new crate
+
+Keep in mind that crate names on crates.io are allocated on a first-come-first-
+serve basis. Once a crate name is taken, it cannot be used for another crate.
+
 ## Packaging a crate
 
 The next step is to package up your crate into a format that can be uploaded to
@@ -43,10 +48,10 @@ are there for the build to succeed. This behavior can be disabled with the
 `--no-verify` flag.
 
 Now’s a good time to take a look at the `*.crate` file to make sure you didn’t
-accidentally package up that 2GB video asset. Cargo will automatically ignore
-files ignored by your version control system when packaging, but if you want to
-specify an extra set of files to ignore you can use the `exclude` key in the
-manifest:
+accidentally package up that 2GB video asset. There is currently a 10MB upload
+size limit on `*.crate` files. Cargo will automatically ignore files ignored by
+your version control system when packaging, but if you want to specify an extra
+set of files to ignore you can use the `exclude` key in the manifest:
 
 ```toml
 [package]
@@ -88,15 +93,13 @@ Be sure to check out the [metadata you can
 specify](manifest.html#package-metadata) to ensure your crate can be discovered
 more easily!
 
-## Restrictions
-
-There are a few restrictions when publishing a crate in the registry:
+# Publishing a new version of an existing crate
 
-* Once a version is uploaded, it can never be overwritten. To upload a new copy
-  of a crate you must upload a new version.
-* Crate names are allocated on a first-come-first-serve basis. Once a crate name
-  is taken it cannot be used for another crate.
-* There is currently a 10MB upload size limit on `*.crate` files.
+In order to release a new version, change the `version` value specified in your
+`Cargo.toml` manifest. Keep in mind [the semver
+rules](manifest.html#the-version-field). Then optionally run `cargo package` if
+you want to inspect the `*.crate` file for the new version before publishing,
+and run `cargo publish` to upload the new version.
 
 # Managing a crates.io-based crate
 
@@ -211,4 +214,4 @@ the “Grant Access” button next to its name:
 
 ![Authentication Access Control](images/auth-level-acl.png)
 
-[crates-io]: https://crates.io/
\ No newline at end of file
+[crates-io]: https://crates.io/

diff --git a/src/doc/header.html b/src/doc/header.html
index 17abf7a89f0b6f1d8cc5ad4e1be24309b74067ce..84544730a5358b49bb580773f36f6a715a26e98d 100644 (file)
--- a/src/doc/header.html
+++ b/src/doc/header.html
@@ -31,7 +31,7 @@
                 <li><a href='index.html'>Getting Started</a></li>
                 <li><a href='guide.html'>Guide</a></li>
                 <li><a href='specifying-dependencies.html'>Specifying Dependencies</a></li>
-                <li><a href='crates-io.html'>Using crates.io</a></li>
+                <li><a href='crates-io.html'>Publishing on crates.io</a></li>
                 <li><a href='faq.html'>FAQ</a></li>
                 <li><a href='manifest.html'>Cargo.toml Format</a></li>
                 <li><a href='build-script.html'>Build Scripts</a></li>

diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index 8c5e0369fcf49d2a671e1136cdadea98d66c897a..371605328724db370a7f7fdfe4174efc507e362d 100644 (file)
--- a/src/doc/manifest.md
+++ b/src/doc/manifest.md
@@ -11,7 +11,11 @@ version = "0.1.0"    # the current version, obeying semver
 authors = ["you@example.com"]
 ```
 
-All three of these fields are mandatory. Cargo bakes in the concept of [Semantic
+All three of these fields are mandatory.
+
+## The `version` Field
+
+Cargo bakes in the concept of [Semantic
 Versioning](http://semver.org/), so make sure you follow some basic rules:
 
 * Before you reach 1.0.0, anything goes.
@@ -23,9 +27,6 @@ Versioning](http://semver.org/), so make sure you follow some basic rules:
   traits, fields, types, functions, methods or anything else.
 * Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
 
-For more on versions, see [this
-documentation](crates-io.html#using-cratesio-based-crates).
-
 ## The `build` Field (optional)
 
 This field specifies a file in the repository which is a [build script][1] for