bug#39640: [PATCH] doc: Document packaging guidelines for Rust crates.

[Efraim Flashner]

On Mon, Feb 17, 2020 at 12:39:22PM +0100, Nicolas Goaziou wrote:
> Hello,
> 
> Efraim Flashner <address@hidden> writes:
> 
> > * doc/contributing.texi (Rust Crates): New section.
> 
> Great! Thank you for this clarification.
> 

I realized I had most of it in my head and that wasn't helping anyone

> > +To prevent namespace collisions we prefix all other rust packages with the
> 
> rust -> Rust
> 
> > +In the rust ecosystem it is common for multiple incompatable versions of a
> 
> Ditto.
> 
> Also incompatable -> incompatible ?
> 

spelling is hard :)

> > +package to be used at any given time, so all packages should have a 
> > versioned
> > +suffix.  If a package has passed version 1.0.0 then just the major version
> > +number is sufficient (e.g.@: rust-clap-2), otherwise the version suffix 
> > should
> > +contain the major and minor version (e.g.@: rust-rand-0.6).
> 
> Nitpick: should contain both the major...
> 
> But that's just me.
> 
> I would also use @code{rust-clap-2} and @code{rust-rand-0.6}

Both sound good.

> 
> > +Because of the difficulty in reusing rust packages as pre-compiled inputs 
> > for
> 
> rust -> Rust
> 
> > +other packages the @xref{cargo-build-system} presents the 
> > @code{#:cargo-inputs}
> 
> @xref is misused here. It targets references at the beginning of
> a sentence. I.e., it will generate
> 
>   ... other packages the See cargo-build-system presents...
> 
> I suggest the more verbose
> 
>   ... other packages the Cargo build system (@pxref{cargo-build-system}) 
> presents...

pxref turned out to be a bit more complicated than I thought. I got it
referring to Build Systems but not to cargo-build-system inside it.
Since the references to gnu-build-system are similar I figured it was
about the same.

> 
> > +and @code{cargo-development-inputs} keywords as build-system arguments.  It
> 
> build-system or build system?
> 

I've always thought of it as build-system due to the keyword, but 'build
system' would be the correct one.

> > Rust @code{dependencies} and @code{build-dependencies}
> > +should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go 
> > in
> > +@code{#:cargo-development-inputs}.  If a rust package links to other 
> > libraries
> 
> rust -> Rust
> 
> Regards,
> 
> -- 
> Nicolas Goaziou

Thanks for the review!

-- 
Efraim Flashner   <address@hidden>   אפרים פלשנר
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

signature.asc
Description: PGP signature