Start to add lots of documentation #899

carols10cents · 2017-07-23T16:17:35Z

I started this a while ago, but an email from @vignesh-sankaran prompted me to get what I have out there rather than bitrotting on my machine.

I'd love a review of what I have so far, @vignesh-sankaran! What do you think of the outline of the architecture document? What kinds of things would make that document a more useful high-level overview?

The doc comments should hopefully make the docs at https://docs.rs/cargo-registry/ better, I don't think the little bit I've added here warrants a version bump and publish yet, though.

jtgeibel · 2017-07-24T00:12:02Z

Hey @carols10cents, here are my cleaned up notes from going through the layout of my working directory. I have this as docs/REPO_LAYOUT.md for now.

Repo File Layout

Backend

build.rs - Cargo build script
Cargo.lock - Locks dependencies to specific versions providing consistency across development and deployment
Cargo.toml - Defines the crate and its dependencies
migrations/ - Diesel migrations applied to the database during development and deployment
.rustfmt.toml - Defines Rust coding style guidelines which are enforced by the CI environment
src/ - The backend's source code
target/ - Compiled output, including dependencies and final binary artifacts - (ignored in .gitignore)
tmp/index-co - The registry repository; in production this is cloned from Github and in development from tmp/index-bare - (ignored in .gitignore)

Front End

app/ - The frontend's source code
config/{environment,targets}.js - Configuration of the frontend
dist/ - Contains the distributable (optimized and self-contained) output of building the frontend; served under the root / url - (ignored in .gitignore)
.ember-cli - Settings for the ember command line interface
ember-cli-build.js - Contains the build specification for Broccoli
.eslintrc.js - Defines Javascript coding style guidelines (enforced during CI???)
mirage/ - A mock backend used during development and testing
node_modules/ - npm dependencies - (ignored in .gitignore)
package.json - Defines the npm package and its dependencies
package-lock.json - Locks dependencies to specific versions providing consistency across development and deployment
public/ - Static files that are merged into dist/ during build
testem.js - Integration with Test'em Scripts
tests/ - Frontend tests
vendor/ - frontend dependencies not distributed by npm; not currently used

Deployment - Heroku

app.json - Configuration for Heroku Deploy Button
.buildpacks - A list of buildpacks used during deployment
config/nginx.conf.erb - Template used by the nginx buildpack
.diesel_version - Used by diesel buildpack to install a specific version of Diesel CLI during deployment
Procfile - Contains process type declarations for Heroku

Development

docs/ - The location of design documentation
.editorconfig - Coding style definitions supported by some IDEs // TODO: Reference extensions for common editors
.env - Environment variables loaded by the backend - (ignored in .gitignore)
.env.sample - Example environment file checked into the repository
.git/ - The git repository; not available in all deployments (e.g. Heroku)
.gitignore - Configures git to ignore certain files and folders
script/init-local-index.sh - Creates registry repositories used during development
tmp/ - Temporary files created during development; when deployed on Heroku this is the only writable directory - (ignored in .gitignore)
tmp/index-bare - A bare git repository, used as the origin for tmp/index-co during development - (ignored in .gitignore)
.travis.yml - Configuration for continous integration at https://travis-ci.org/rust-lang/crates.io
.watchmanconfig - Use by Ember CLI to efficiently watch for file changes if you install watchman

Other

LICENSE-APACHE
LICENSE-MIT
README.md

vignesh-sankaran

Hmm... could we look at removing "The" in front of the headers in docs/ARCHITECTURE.md that refer to backend modules? There's a lot of them :)

vignesh-sankaran · 2017-07-25T11:51:24Z

docs/ARCHITECTURE.md

+
+#### The `utils` module
+
+### Code having to do with managing a registry of crates


Hmm, not quite sure where you're referring to with this?

I'm not sure why you're not sure :) What are the possible interpretations that you're deciding between? Note that this has an h3, and the h4s from line 102 to 126 are under this heading, does that help? What would be a better heading?

I was trying to figure out how this fit into one module, yes I didn't see the h3 for it compared to the h4's that refer to specific modules :)

vignesh-sankaran · 2017-07-25T11:52:31Z

Thanks for starting on this @carols10cents, the structure of the document itself looks good, though I think we should mention that it's specifically for the backend. Maybe we could look into having a similar document for the front end too?

Also, maybe we could look at adding a diagram of the database schema?

carols10cents · 2017-07-26T23:17:01Z

though I think we should mention that it's specifically for the backend. Maybe we could look into
having a similar document for the front end too?

Yeah, I have a heading in there for backend and I think I just got tired before making a corresponding frontend heading :)

Hmm... could we look at removing "The" in front of the headers in docs/ARCHITECTURE.md that refer to backend modules? There's a lot of them :)

🤷‍♀️ That's how I'd talk about them though... "Where's the code to do x?" "it's in the db module"

Also, maybe we could look at adding a diagram of the database schema?

I'd be into that, if there's a tool we can use to automate creating the diagram and if we keep it up to date :) Do you know of a good one?

carols10cents · 2017-07-26T23:49:14Z

Ok -- I've incorporated @jtgeibel's repo layout docs and took @vignesh-sankaran's suggestion to break this out into separate backend and frontend documents-- I could see this getting long :)

WDYT?

vignesh-sankaran · 2017-07-27T00:38:49Z

docs/ARCHITECTURE.md

+
+[conduit]: https://crates.io/crates/conduit
+
+These files have to do with the backend:


How about "these files and directories"?

jtgeibel · 2017-07-27T04:55:52Z

docs/ARCHITECTURE.md

+
+Documentation about the codebase appears in these locations:
+
+* `LICENSE-APACHE` and `LICENSE-MIT` - the terms under which this codebase is licensed.


It looks like package.json only lists MIT. I'm not sure if that is an oversight or if we need to word this more carefully. We should probably explicitly call out dual licensing in README.md

Also see: https://docs.npmjs.com/files/package.json#license

920: Doc comments on new pull requests r=carols10cents Along the lines of #899, we should start mandating doc comments on all new types and functions, and encourage doc comments on modified types. Is there a way to check for this in TravisCI as well?

carols10cents · 2017-08-02T13:37:17Z

I've addressed the two things yinz pointed out, and in the interest of getting this merged so that we can all start working on this, and because this is all just docs, I'm going to merge my own PR 😎

bors r+

@vignesh-sankaran

899: Start to add lots of documentation r=carols10cents I started this a while ago, but an email from @vignesh-sankaran prompted me to get what I have out there rather than bitrotting on my machine. I'd love a review of what I have so far, @vignesh-sankaran! What do you think of the outline of the architecture document? What kinds of things would make that document a more useful high-level overview? The doc comments should hopefully make the docs at https://docs.rs/cargo-registry/ better, I don't think the little bit I've added here warrants a version bump and publish yet, though.

bors-voyager · 2017-08-02T13:52:17Z

Build succeeded

continuous-integration/travis-ci/push

carols10cents added the S-waiting-on-review label Jul 23, 2017

vignesh-sankaran reviewed Jul 25, 2017

View reviewed changes

carols10cents force-pushed the document-architecture branch from 6c831d6 to 380704b Compare July 26, 2017 23:45

Add lots of documentation

4c43811

carols10cents force-pushed the document-architecture branch from 380704b to 4c43811 Compare July 26, 2017 23:49

vignesh-sankaran reviewed Jul 27, 2017

View reviewed changes

jtgeibel reviewed Jul 27, 2017

View reviewed changes

vignesh-sankaran mentioned this pull request Jul 28, 2017

Doc comments on new pull requests #920

Merged

carols10cents added 2 commits August 2, 2017 09:23

Directories too

93fb656

Correct license in package.json

25383e5

bors-voyager bot merged commit 25383e5 into rust-lang:master Aug 2, 2017

carols10cents deleted the document-architecture branch August 2, 2017 14:06

Turbo87 removed the S-waiting-on-review label Dec 3, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Start to add lots of documentation #899

Start to add lots of documentation #899

Uh oh!

carols10cents commented Jul 23, 2017

Uh oh!

jtgeibel commented Jul 24, 2017

Uh oh!

vignesh-sankaran left a comment •

edited

Loading

Uh oh!

vignesh-sankaran Jul 25, 2017

Uh oh!

carols10cents Jul 26, 2017

Uh oh!

vignesh-sankaran Jul 27, 2017 •

edited

Loading

Uh oh!

vignesh-sankaran commented Jul 25, 2017 •

edited

Loading

Uh oh!

carols10cents commented Jul 26, 2017

Uh oh!

carols10cents commented Jul 26, 2017

Uh oh!

vignesh-sankaran Jul 27, 2017

Uh oh!

jtgeibel Jul 27, 2017

Uh oh!

carols10cents commented Aug 2, 2017

Uh oh!

bors-voyager bot commented Aug 2, 2017

Uh oh!

Uh oh!


		#### The `utils` module

		### Code having to do with managing a registry of crates


		[conduit]: https://crates.io/crates/conduit

		These files have to do with the backend:


		Documentation about the codebase appears in these locations:

		* `LICENSE-APACHE` and `LICENSE-MIT` - the terms under which this codebase is licensed.

Start to add lots of documentation #899

Start to add lots of documentation #899

Uh oh!

Conversation

carols10cents commented Jul 23, 2017

Uh oh!

jtgeibel commented Jul 24, 2017

Repo File Layout

Backend

Front End

Deployment - Heroku

Development

Other

Uh oh!

vignesh-sankaran left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vignesh-sankaran Jul 25, 2017

Choose a reason for hiding this comment

Uh oh!

carols10cents Jul 26, 2017

Choose a reason for hiding this comment

Uh oh!

vignesh-sankaran Jul 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vignesh-sankaran commented Jul 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

carols10cents commented Jul 26, 2017

Uh oh!

carols10cents commented Jul 26, 2017

Uh oh!

vignesh-sankaran Jul 27, 2017

Choose a reason for hiding this comment

Uh oh!

jtgeibel Jul 27, 2017

Choose a reason for hiding this comment

Uh oh!

carols10cents commented Aug 2, 2017

Uh oh!

bors-voyager bot commented Aug 2, 2017

Build succeeded

Uh oh!

Uh oh!

vignesh-sankaran left a comment •

edited

Loading

vignesh-sankaran Jul 27, 2017 •

edited

Loading

vignesh-sankaran commented Jul 25, 2017 •

edited

Loading