Introduce Rust guide

[natelust]

This is a first draft of the proposed rust developer guide. All comments and improvement welcome.

[TallJimbo]

Two big-picture comments (some echoed in various line-comments):

• I think you need to mention rubinoxide up front concretely and organize the discussion around that; only talking about organizing code in a purely abstract sense makes the actual guidelines a lot harder to follow.
• There are a lot of start-of-section sentences here that just sound like software platitudes. I understand wanting to have some sort of introductory text for each section, but I think the audience (who is likely reading it as fast as they can so they can get back to writing code) will appreciate it if you just dive right in.

[nealmcb]

Note a few typos

[taranu]

This guide seems written for an audience that has decided to add new rust code. It needs content for developers who barely know anything about rust and:

• want to know what functionality is available and where/how it can/should be used
• might one day have to review a ticket with (slightly) non-trivial rust changes

Some of this is covered by the Introduction, Resources and Code Organization sections, but not entirely. For example, say I need some performant vectorized code for numpy arrays. Should I look to numpy first? If scipy/astropy has what I need, should I also check rubinoxide for relevant functions first and benchmark them?

Similarly, what does leverage its memory safety features mean? Writing only code without unsafe?

[taranu]

Is make really the best option here?

[natelust]

Here yes it is. It is the simplest way to coordinate a few of the backend technologies in a readable way that is also supported by our eupspkg build system already.

[natelust]

This guide seems written for an audience that has decided to add new rust code. It needs content for developers who barely know anything about rust and:

• want to know what functionality is available and where/how it can/should be used
• might one day have to review a ticket with (slightly) non-trivial rust changes

Some of this is covered by the Introduction, Resources and Code Organization sections, but not entirely. For example, say I need some performant vectorized code for numpy arrays. Should I look to numpy first? If scipy/astropy has what I need, should I also check rubinoxide for relevant functions first and benchmark them?

Similarly, what does leverage its memory safety features mean? Writing only code without unsafe?

I have added a bit of language to the text addressing some of your concerns, with a bit of offline conversation with @TallJimbo .

As is already the case for our current c++ code, most developers can read trivially small changes to rust code, and if they do not feel comfortable doing a review are free to say so and it is on the author to find someone to review the changes who does. It is hopped that this guide will generate uniform enough code that people can "lean by example" cargo-culting from similar code already present to help boot strap into more rust knowledge.

On discoverability, this is not really much of a different problem. to what we have in the stack in general (both c++ and python) and should not be held to any different of a standard. The guide does talk about documentation for code that will be bound to python, and that documentation will show up in the standard pipelines.lsst.io along side all the other documentation we have.