diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md
index 58d4a446d..ad1289049 100644
--- 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
+# Publishing a new version of an existing crate
-There are a few restrictions when publishing a crate in the registry:
-
-* 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:
-[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 17abf7a89..84544730a 100644
--- a/src/doc/header.html
+++ b/src/doc/header.html
@@ -31,7 +31,7 @@
Getting Started
Guide
Specifying Dependencies
- Using crates.io
+ Publishing on crates.io
FAQ
Cargo.toml Format
Build Scripts
diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index 8c5e0369f..371605328 100644
--- 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