I meant to chime in earlier with my two cents and experience.
So overall, I did not find contributing to the compiler particularly difficult, compared to other large projects. This is an achievement in and of itself, great job! Some of my comments my appear negative below, but let me assure you, they first of all come from a place of love, and in reality, contributing to rustc is quite nice experience here from a bureaucratic and technical perspective, congrats! In contrast for example, many moons ago I had a (couple) patches take over 3 months to go into LLVM, and even then, I didn’t even get credit for it, they were cherry-picked!
That being said, I would say the most distressing thing about hacking on the compiler is the internal documentation, but not really a lack of it, but rather some of it being either misleading, literally incorrect, or superfluous.
I found this more frustrating than anything; e.g., I would expect that a comment like this to be accurate, but is not (as an aside, i.e., in this particular case, we do not, contrary to the statement, do C++ name mangling, though it is substantially complicated by the linux C++ name mangler now supporting “rust mangling style”…)
At my company there is a strong culture of distrust of inline source code comments (e.g. above), as opposed to just reading the source code directly, for just precisely this reason - the comment goes out of sync/isn’t maintained/is no longer true/was true and now serves actually to hamper the reader by acting as a red herring.
I can provide more examples across other portions of the codebase, and I haven’t really read a lot, mostly just related to debugging and symbols, etc. This is worrisome to me…
Some other things off the top of my head, which some people may or may not have mentioned perhaps:
- An “index” for the major components of rustc/rust would be great; google’s libc implementation’s README is a really great example of this: https://github.com/aosp-mirror/platform_bionic#what-are-the-big-pieces-of-bionic . I suppose that the README in the
rust/src/librustc/README.md counts, but its not very easy to find, isn’t necessarily the first place you’d look, etc. One problem is that the rust repo also contains libstd, etc. The root README has great instructions for building, but still not an overview of the source code structure; the google example above is great - it’s short and to the point!
- Who to ask what - I’m not sure how to solve this, but it would be nice if you had a set of “experts” who have certain fundamental knowledge about particular portions of the codebase, and one could drop a line somehow to ask for clarification, etc. For example, I had a build failure in the debug testing language (which is still a mystery to me), and I still don’t know who knows how it works, or where its even documented how its supposed to work: https://github.com/rust-lang/rust/pull/46457#issuecomment-351539880
- Better compile times ; it would be really great if cargo check existed in the codebase; when you’re just starting to hack, quick feedback is nice to play with different types, what’s ok, what isn’t, etc.
- Rust compiler jargon - I’m really not sure why some of it took off or why it should be exist, and I find it a little strange, but whatever I guess.
- There appears to be a deep LLVM bias in the codebase and among devs
I don’t want to offend anyone with the last comment, and its not a bad thing at all, LLVM is great, but I’ve had several occasions with online discussions where it appeared this was actually causing a communication issue, as they only understood the backend in llvm terms (which takes care of some of the more ABI/binary-esque issues for you, and consequently, I suppose, one never therefore needs to think of it), whereas I approach these kind of things more from a “this is what I’m holding in my hand, e.g., the actual emitted binary”. Incidentally, this actual emitted binary is what debuggers and other tools only get to look at, so it definitely helped me notice and track down some related bugs (and know how to start to fix them without too much catch-up work).
On a similar note, a few times I felt like I was being condescended to when spoken to or having questions answered, and while possibly a result of the difficulties of online communication, I did think I should mention it, as I’m not super motivated to contribute again.
I guess that’s kind of a bummer thing to end on so I’d like to reiterate that all of the devs have done great work and to keep it up