[rust-dev] Migrating libs out of rust-lang/rust

Simon Sapin simon.sapin at exyr.org
Wed Jul 30 02:44:28 PDT 2014


On 29/07/14 23:30, Alex Crichton wrote:
> [...]
>
> We plan to implement any necessary infrastructure to ensure that the crates
> move out of the rust repository maintain the same level of quality they
> currently have.

Will these crates’ documentation be available online?

In rust-url, rust-cssparser, and Servo, I have Travis-CI setup to 
generate documentation with rustdoc and, for successful builds on 
master, upload it to GitHub Pages. The end result looks like this:

http://servo.github.io/rust-cssparser/cssparser/index.html

See at the end of this email for how this works.


Long term, I’d like Rust to have an official package index, like 
Python’s PyPI: https://pypi.python.org/

PyPI provides free hosting for documentation of Python projects. I’d 
like Rust to have something like this too. GitHub Pages works and exists 
now, but I’m not a fan of generated files in the source repository, even 
in a separate branch.


> To this extent, the current process for moving a crate out of the standard
> distribution will be as follows:
>
> 1. A member of the core team will be contacted to create the repository
>    `rust-lang/$foo`.
> 2. A PR will be made against `rust-lang/$foo`

I’ve just checked: GitHub does not allow forking (and therefore making 
PRs to) an empty repository, so the person creating the repository will 
have to at least check the "Initialize this repository with a README" 
checkbox to make a dummy first commit.


>     with the current copy of the
>     code from `rust-lang/rust`. This PR will be expected to have the
>     following source structure:
>
>       * Cargo.toml - a manifest to build this repo as a cargo package
>       * .travis.yml - configuration to run automated tests on travis. A
>                       sample can be found for hexfloat [1]
>       * LICENSE-{MIT,APACHE} - copied over from rust-lang/rust
>       * src/ - the same source structure as the folder in rust-lang/rust

This should also include a README.md file containing at least of copy of 
the crate’s docstring.


> 3. A PR will be made against `rust-lang/rust` which will flag the relevant
>     library as `#[deprecated]` with a message pointing at `rust-lang/$foo`
>
> In order to ensure that these repositories continue to stay up to date, we
> will have the following process in place:
>
> 1. Each repository will be hooked up to Travis CI and will be built each
>     night once the new nightlies are available.

How will this be achieve? http://www.rust-ci.org/ does it, but I’d like 
to see something more "official" and tied to the rust-lang.org binary 
nightlies rather than the Ubuntu PPA.


> [...]


Regarding documentation on GitHub pages mentioned earlier, the script 
doing it looks like this:

https://github.com/servo/rust-cssparser/blob/331e5695dc/.travis.yml

The `<meta http-equiv=refresh ...` line is so that the URL 
http://servo.github.io/rust-cssparser/ is not a 404 error. (rustdoc does 
not generate anything there.)

ghp-import resets a git branch (defaults to gh-pages) to contain exactly 
what’s in a given directory, regardless of what the branch previously 
contained.

The "secure" line is created with `travis encrypt -r 
servo/rust-cssparser TOKEN=[hex string]`, where [hex string] is a GitHub 
access token for a user with push access to the repository. (I created 
https://github.com/rustdoc for this purpose.)

http://docs.travis-ci.com/user/encryption-keys/
https://help.github.com/articles/creating-an-access-token-for-command-line-use

-- 
Simon Sapin


More information about the Rust-dev mailing list