Stream: t-compiler/wg-learning

Topic: forge vs rustc-guide


nikomatsakis (May 13 2019 at 20:08, on Zulip):

So @Santiago Pastorino the question of forge vs rustc-guide is a good one --

nikomatsakis (May 13 2019 at 20:08, on Zulip):

my sense is that maybe they are not both needed, but maybe we can make a split that makes sense

nikomatsakis (May 13 2019 at 20:09, on Zulip):

rustc-guide would presumably be focused on "how rustc works" -- understanding the code

nikomatsakis (May 13 2019 at 20:09, on Zulip):

forge would more about general procedures ( or perhaps things other than rustc )

nikomatsakis (May 13 2019 at 20:09, on Zulip):

but I feel like there's a lot of "mixed material"

nikomatsakis (May 13 2019 at 20:09, on Zulip):

e.g., instructing people on workflows for using x.py build

nikomatsakis (May 13 2019 at 20:10, on Zulip):

I don't know what org is best really and don't care that much, except that I think some kind of "table of contents" that dives into how rustc works is good,

nikomatsakis (May 13 2019 at 20:10, on Zulip):

we've already sort of divided rustc-guide into two sections

nikomatsakis (May 13 2019 at 20:10, on Zulip):

maybe some of that "contributing to rustc" material should go to forge

nikomatsakis (May 13 2019 at 20:10, on Zulip):

and the rustc-guide should just link to it

Santiago Pastorino (May 13 2019 at 20:17, on Zulip):

my sense is that maybe they are not both needed, but maybe we can make a split that makes sense

I guess defining a clear line would be a good idea

Santiago Pastorino (May 13 2019 at 20:19, on Zulip):

forge would more about general procedures ( or perhaps things other than rustc )

I guess, rustc-guide purpose is more clear, forge is imo what needs to be more clearly defined

nikomatsakis (May 13 2019 at 20:20, on Zulip):

stuff like the rustc bug fix procedure you highlighted is kind of unclear

nikomatsakis (May 13 2019 at 20:20, on Zulip):

and then there is also the compiler-team repository

nikomatsakis (May 13 2019 at 20:20, on Zulip):

which has some procedures

nikomatsakis (May 13 2019 at 20:21, on Zulip):

(maybe those should be hoisted to forge?)

nikomatsakis (May 13 2019 at 20:21, on Zulip):

sigh =)

Santiago Pastorino (May 13 2019 at 20:21, on Zulip):

in forge seems to be some stuff that could be moved into rustc-guide and then there seems to be infra stuff

Santiago Pastorino (May 13 2019 at 20:21, on Zulip):

or procedures

Santiago Pastorino (May 13 2019 at 20:21, on Zulip):

well maybe I'm using infra in a broad way

nikomatsakis (May 13 2019 at 20:21, on Zulip):

I guess I think that it probably makes sense to put things that pertain to rustc specifically in rustc-guide

centril (May 13 2019 at 20:24, on Zulip):

there's some lang stuff as well

centril (May 13 2019 at 20:24, on Zulip):

like the rfc merge procedure (which is mostly for me)

centril (May 13 2019 at 20:24, on Zulip):

and triage procedure (for t-release)

Santiago Pastorino (May 13 2019 at 20:26, on Zulip):

maybe we can have a https://dev-doc.rust-lang.org/ as a landing page for all these things

Santiago Pastorino (May 13 2019 at 20:27, on Zulip):

rustc-guide linked from there, also rustc API, procedures, etc

Santiago Pastorino (May 13 2019 at 20:27, on Zulip):

could start being like forge but with the https://doc.rust-lang.org/ look and feel :)

centril (May 13 2019 at 20:30, on Zulip):

A dense list of items to different list sounds good

nikomatsakis (May 13 2019 at 20:31, on Zulip):

I do like the name "forge" :)

centril (May 13 2019 at 20:31, on Zulip):

:hammer_and_wrench:

nikomatsakis (May 13 2019 at 20:31, on Zulip):

but yeah I think the idea of a meta directory is good

nikomatsakis (May 13 2019 at 20:31, on Zulip):

I find https://doc.rust-lang.org/ kind of .. hard to navigate though, tbh

Iñaki Garay (May 13 2019 at 20:31, on Zulip):

maybe we can have a https://dev-doc.rust-lang.org/ as a landing page for all these things

I would like to contribute that as a newcomer, the #1 thing that feels overwhelming is the amount of different sources of information on all the tools and procedures. that they exist is fantastic but 'where to look' and 'what is important first' are two very difficult to answer questions

Santiago Pastorino (May 13 2019 at 20:32, on Zulip):

@Iñaki Garay nailed it exactly

Santiago Pastorino (May 13 2019 at 20:32, on Zulip):

I think having a root place where you can find everything is a good first step to fix the issue

centril (May 13 2019 at 20:32, on Zulip):

@nikomatsakis perhaps use a column based layout where each column is for e.g. "rustc", "rfcs", "infra", "triage", ...

Santiago Pastorino (May 13 2019 at 20:33, on Zulip):

I'm not sure if forge is even linked from somewhere

Iñaki Garay (May 13 2019 at 20:33, on Zulip):

I find https://doc.rust-lang.org/ kind of .. hard to navigate though, tbh

I was looking at that page at this precise moment and was thinking that adding to it would not be a good idea, especially for non-developers

Santiago Pastorino (May 13 2019 at 20:34, on Zulip):

yeah, I was not trying to say that doc is great

Santiago Pastorino (May 13 2019 at 20:34, on Zulip):

I think it would be nice to have a root landing site where you can find everything

centril (May 13 2019 at 20:34, on Zulip):

@Santiago Pastorino @nikomatsakis developer.rust-lang.org

Santiago Pastorino (May 13 2019 at 20:34, on Zulip):

I don't think the name is the important thing

Santiago Pastorino (May 13 2019 at 20:34, on Zulip):

could be even forge

Santiago Pastorino (May 13 2019 at 20:35, on Zulip):

to me whatever is fine

centril (May 13 2019 at 20:35, on Zulip):

ah yeah; true

Santiago Pastorino (May 13 2019 at 20:35, on Zulip):

but I think we need something that is recognized as the starting point for rust development

Santiago Pastorino (May 13 2019 at 20:35, on Zulip):

first thing would be recognizing that something is missing :)

centril (May 13 2019 at 20:35, on Zulip):

yeah forge should probably be it

Iñaki Garay (May 13 2019 at 20:38, on Zulip):

so the crux is that
- rustc-guide is documentation for people contributing to the compiler specifically
- the goal of forge is not clear but should be something like 'documentation for contributors to the rust ecosystem in general'
- forge should look like doc.rust-lang.org
?

Santiago Pastorino (May 13 2019 at 20:39, on Zulip):

unsure if the last point is important :), I've suggested that but probably not important

Iñaki Garay (May 13 2019 at 20:39, on Zulip):

yeah

Santiago Pastorino (May 13 2019 at 20:40, on Zulip):

it's just that because of the look and feel, not being linked (or at least I think it's not) from the main site or somewhere, to me seems like an unofficial thing

Santiago Pastorino (May 13 2019 at 20:41, on Zulip):

I'm not even sure if the information there is correct and updated

Iñaki Garay (May 13 2019 at 20:42, on Zulip):

IMHO forge should be linked to from doc.rust-lang.org under a proper heading

Santiago Pastorino (May 13 2019 at 20:42, on Zulip):

yeah, I think that too :)

Santiago Pastorino (May 13 2019 at 20:43, on Zulip):

there you can find

Santiago Pastorino (May 13 2019 at 20:43, on Zulip):

The rustc Contribution Guide

The rustc Guide documents how the compiler works and how to contribute to it. This is useful if you want to build or modify the Rust compiler from source (e.g. to target something non-standard).

Santiago Pastorino (May 13 2019 at 20:44, on Zulip):

maybe is more proper to have something about forge there

Santiago Pastorino (May 13 2019 at 20:44, on Zulip):

and in forge you will find the guide

mark-i-m (May 13 2019 at 20:48, on Zulip):

So the guide that I have been trying to follow when moving stuff over from the forge is:
- if it is useful for contributing to rustc, it goes in the rustc-guide
- if it pertains to some other part of the project (e.g. libstd, clippy, etc) it should go somewhere else
- infra stuff and team procedures (i.e. stuff that a rust team member would use, but not relevant to most people) goes in the forge

mark-i-m (May 13 2019 at 20:49, on Zulip):

I find https://doc.rust-lang.org/ kind of .. hard to navigate though, tbh

I find it visually hard to parse. There are too many headings and font sizes

centril (May 13 2019 at 20:54, on Zulip):

@mark-i-m I think contribution guides to libstd could be in the rustc guide

centril (May 13 2019 at 20:54, on Zulip):

but under a special chapter

centril (May 13 2019 at 20:54, on Zulip):

But doc.rust-lang.org looks bad :P

centril (May 13 2019 at 20:55, on Zulip):

Forge probably looks good, it just needs some polish and to be updated

mark-i-m (May 13 2019 at 20:56, on Zulip):

@centril I don't really have fundamental objections, but I also don't know how much there is to write. If it was self-contained enough for a single subchapter, I think that would be reasonable. But if it became a large portion of the guide, I would be more hesitant

mark-i-m (May 13 2019 at 20:56, on Zulip):

Forge probably looks good, it just needs some polish and to be updated

Agree :+1: forge >> docs.rlo

centril (May 13 2019 at 20:57, on Zulip):

@mark-i-m I think there's plenty of things to say:

1. How to deal with #[(un)stable ...]
2. How to deal with unsafe { ... } in there.
3. How to deal with tests

mark-i-m (May 13 2019 at 20:58, on Zulip):

Hmm... in that case, perhaps it's worth it's own guide?

mark-i-m (May 13 2019 at 20:58, on Zulip):

not sure tbh

centril (May 13 2019 at 20:59, on Zulip):

@mark-i-m probably not because ./x.py is how you interact with contributions

mark-i-m (May 13 2019 at 20:59, on Zulip):

What do you mean

mark-i-m (May 13 2019 at 20:59, on Zulip):

?

centril (May 13 2019 at 20:59, on Zulip):

and it's a good idea to make libstd contributions a lead-in to general compiler dev

centril (May 13 2019 at 21:00, on Zulip):

@mark-i-m to build and test libstd you use ./x.py

Amanjeev Sethi (May 13 2019 at 21:01, on Zulip):

I did not know forge existed until today. :sorry:

mark-i-m (May 13 2019 at 21:01, on Zulip):

@centril true, but that doesn't seem like a super strong connection to me... if that's the criteria then a large chunk of the rust project should be in the guide

mark-i-m (May 13 2019 at 21:01, on Zulip):

how do we limit its scope?

mark-i-m (May 13 2019 at 21:01, on Zulip):

or should we limit its scope?

centril (May 13 2019 at 21:04, on Zulip):

@mark-i-m A bunch of things in the rustc guide are relevant, at minimum chapters 1-5,

centril (May 13 2019 at 21:05, on Zulip):

and a bunch of libstd stuff are really part of the compiler

centril (May 13 2019 at 21:05, on Zulip):

e.g. all lang items and intrinsics at minimum

mark-i-m (May 13 2019 at 21:05, on Zulip):

also true

mark-i-m (May 13 2019 at 21:05, on Zulip):

hmmm

mark-i-m (May 13 2019 at 21:05, on Zulip):

perhaps a topic for discussion tomorrow?

centril (May 13 2019 at 21:05, on Zulip):

I think mostly it's convenient to have them colocated to give a "holistic contributor experience"

centril (May 13 2019 at 21:06, on Zulip):

yeah that sgtm; not sure I can attend, but go ahead

Last update: Nov 15 2019 at 20:40UTC