Book: When we're done with the rewrite, will this repo stay or be folded into rust-lang/rust?

[carols10cents]

So in #131, we said:

So this repo is getting merged into rust-lang/rust eventually

It's not clear if that's happening or not; but either way, it will still be distributed with Rust, and in general, it's always better to make stuff work offline if possible.

And looking at this comment from nostarch, I realized if we print a link to this repo on paper, we should not then get rid of this repo 😳

I kind of like that this is a separate repo because:

• You don't have to wade through all of rustc's source code to just work on the book
• Potentially less intimidating to contributors
• Can use different conventions for, say, issue labels

I kind of don't like that this is a separate repo because:

• Patches to the book don't get "counted" as "rust" contribs, even though doc contribs should be valued as much as code contribs
• We'd have to do extra work to change the build process of rustc to pull from this repo

I mean, I guess we could just change this repo to have nothing but a README explaining how to find and contribute to the book in rust-lang/rust...

But I think we should know what our plan is before chapter 1 gets finalized.

[azerupi]

From a casual contributors perspective I would very much like to see the book stay in it's own repository :blush:

It will redirect most doc issues to this repository making them so so much more visible!
You could "watch" this repo without getting overwhelmed by the high trafic in the main repo and at the same time, noise due to doc issues will decrease in the main repo.

[steveklabnik]

@brson and I have chatted about this a bit, the biggest difference is that in order to stay in a different repository, the way we build docs.rust-lang.org would have to change.

[steveklabnik]

Patches to the book don't get "counted" as "rust" contribs, even though doc contribs should be valued as much as code contribs

I have wanted to port http://contributors.rubyonrails.org/faq ever since @iirelu contributed to Cargo back in the like.... 1.2 days? That way, we can actually show who all contributes to all the repos, not just rust-lang/rust.

[brson]

Having better ways to celebrate contributors across all repos is something that would help motivate important out-of-tree work generally. Today TWiR is probably the main place where we regularly surface contributions, I wonder if the way those contributions are reported could be improved to emphasize non-rust-lang/rust contributions. e.g. it could organize them by repo. cc @nasa42 @llogiq

I do prefer to keep the book out the main repo. I haven't thought about how that would impact the build process but suspect that creating the book and doc index would go in https://github.com/rust-lang/rust-packaging. Although I also yearn to rewrite the build process from scratch to simplify it. Right now it involves a lot of distributed steps and code distributed across rust-lang/rust, cargo, rust-packaging, and rust-buildbot. It will get more complex with book2, and with integrating rustfmt, clippy etc. Borderline unmanagable. What I'd like is a single rust-packaging2 repo that builds everything all together. There's no reason for us to have separate cargo nigthlies. Hm, sorry, tangent.

[brson]

Also, once we're ready to distribute the book2 without integrating it back into the main repo, that calls into question where book1 lives, the nomicon, maybe other things.

[carols10cents]

@shepmaster pointed out that he's linked to book1 in a lot of places on stackoverflow, so it would be nice to keep those links working. Even nicer would be to have a header on those pages that say something like "You're reading v1 of the book, there's a v2 available here!"

[carols10cents]

I think this question has been decided: this repo will remain separate.

I'm going to close this issue, then-- there are more questions/issues here, but I feel like they belong in other repos (but I'm not sure which):

• Making this book available under doc.rust-lang.org
  
  
  
  • When should we start doing this?
  
  
  • What should the URLs be?
  
  
  • Actually doing the work to make it available
  
  
• Shipping this book with Rust installations
  
  
  
  • When should we start doing this?
  
  
  • Actually doing the work to make it available
  
  
• Keeping the old book around
  
  
  
  • Should we keep the old book around indefinitely, on doc.rust-lang.org and shipped with Rust installations? If not, when should it be removed?
  
  
  • Should the old book stay in the rust-lang repo?
  
  
  • Actually doing the work for whatever we decide
  
  

If someone tells me which repo these issues belong in (here? rust-lang/rust? rust-lang/rust-www? somewhere else?), I would be happy to create them.

[carols10cents]

I filed new issues in this repo for the first two top-level bullets:

• https://github.com/rust-lang/book/issues/235
• https://github.com/rust-lang/book/issues/236

I think the third top-level bullet having to do with the old book belongs in rust-lang rust, so I filed it there:

• https://github.com/rust-lang/rust/issues/36094