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

[Efraim Flashner <efraim@flashner.co.il>]

* doc/contributing.texi (Rust Crates): New section.
---
 doc/contributing.texi | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index c6586a2adf..2fb641f0c5 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -347,6 +347,7 @@ needed is to review and apply the patch.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
 * Java Packages::               Coffee break.
+* Rust Crates::                 Beware of oxidation.
 * Fonts::                       Fond of fonts.
 @end menu
 
@@ -665,6 +666,39 @@ are also prepended by @code{perl-}.  Such modules tend to have the word
 prefix.  For instance, @code{libwww-perl} becomes @code{perl-libwww}.
 
 
+@node Rust Crates
+@subsection Rust Crates
+
+@cindex rust
+Rust programs standing for themselves are named as any other package, using the
+lowercase upstream name.
+
+To prevent namespace collisions we prefix all other rust packages with the
+@code{rust-} prefix.  The name should be changed to lowercase as appropriate and
+dashes should remain in place.
+
+In the rust ecosystem it is common for multiple incompatable versions of a
+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).
+
+Because of the difficulty in reusing rust packages as pre-compiled inputs for
+other packages the @xref{cargo-build-system} presents the @code{#:cargo-inputs}
+and @code{cargo-development-inputs} keywords as build-system arguments.  It
+would be helpful to think of these as similar to @code{propagated-inputs} and
+@code{native-inputs}.  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
+then the standard placement in @code{inputs} and the like should be used.
+
+Care should be taken to ensure the correct version of dependencies are used; to
+this end we try to refrain from skipping the tests or using @code{#:skip-build?}
+when possible.  Of course this is not always possible, as the package may be
+developed for a different Operating System, depend on features from the Nightly
+Rust compiler, or the test suite may have atrophied since it was released.
+
+
 @node Java Packages
 @subsection Java Packages
 
-- 
2.25.0