# rust project stuff that kinda sucks

**note: this is about stuff that sucks *when working on rust itself*, not stuff in the language**

See also the [discussion on Zulip](https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/.28editable.29.20list.20of.20ways.20contributing.20to.20rust.20is.20frustrating).

## finding things

- finding work (esp for new contributors)
- easy issues get snapped up right away
- harder issues often don't have mentoring because maintainers are overwhelmed and don't feel it's worth the effort if people are likely to bounce off after the first change
- [the issue tracker sucks](#issue-tracker-sucks)
- Some prior discussions on a [project ideas catalogue](https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/Creating.20a.20Project.20Ideas.20Catalogue), this is probably like Niko's [Rust Project Goals initiative](https://github.com/rust-lang/rust-project-goals)?
- finding relevant experts for a piece of code:
- who knows about/maintains a bit of code
- who has the review capacity and willingness to be assigned non-randomly-rolled PRs involving the relevant areas
- who can be pinged to give advice but not necessarily extensively review
- who is willing to mentor (at a high level)
- identifying duplicate issues / PRs is hard
- finding the state/history of an issue or change
- esp. bad when discussion happened on IRC or in-person
- more common for older issues
- triage team itself has trouble with this
- it's hard to follow through the entire discussion if it's fragmented across multiple platforms (e.g. GitHub, Zulip, Internals, etc.)
- finding which problems block others
- hard to know where to start when working on a complex issue
- `S-blocked` or other kind of block status is tracked ad-hoc and easy to become stale / inaccurate
- finding where docs live
- forge is very hard to find and rarely linked
- lots of knowledge is [in random hackmds](https://hackmd.io/5n97FexORfiOjhFShK9HpA)
- even in zulip it's not always easy to find the relevant discussion unless you happen to know key relevant search terms
- here's [a list](https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/list.20of.20hackmds) of all the hackmds
- 

### issue tracker sucks

- missing tracking issues
- unclear backlog / which issues are important
- not maintained by anyone
- closest thing we have is S-needs-triage but we rarely go back and triage old issues (there's also still a bunch of `S-needs-triage-legacy` issues on top of the ones not even labelled as legacy)
- triage team doesn't look at issue tracker
- wg-triage + other contributors who help with triage doesn't really have any regular discussions for "hard to triage" issues, issue triaging currently basically relies on *someone* who happens to have the time, knowledge and motivation to help triage some issues

## onboarding

- joining a team is scary and we don't do much to make it less scary
- would be great if new contributors/members are given a brief walkthrough of the organization of whatever the team is responsible for, and who's working on what, and team priorities (if there even is any explicit documentation for such)
- no guidance for reviewers
- if I don't feel comfortable/confident reviewing/approving this PR, who do I pass the hot potato to?
- no guidance for team leads!
- no guidance for FCP's
- Do I need to say that a feature looks "good", and I'm comfortable signing off on shipping it, or just that I can't see anything wrong with it?
- Related: You can join a team for expertise in one area, an then need to do FCP's on areas you have no context for.
- people feel lost in meetings
- never given an overview of the code you're responsible for
- for new contributors: "there are meetings?"
- Meetings with several agenda items can be an hour long debate about one of them.
- can't have review priviledges without also having to look at FCPs
- some teams address this with contributor sub teams (compiler, libs, rustdoc)
- t-compiler is addressing this by changing team structure [rfcs#3599](https://github.com/rust-lang/rfcs/pull/3599)
- people don't know each other well; not "fun"
- clippy is an exception! clippy is an exception to lots of these things! we should look at what they are doing!

## maintaining

- writing a changelog is a lot of work for unclear reward
- ed page says this (the cargo progress report, which is more than just a changelog) takes him two full days each cycle
- reviewing is asymmetric; often takes more effort than opening a PR
- review queue grows without bound
- [previous discussion](https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/review.20queue.20.26.20capacity)
- review bandwidth is very limited
- long delays between reviews and before initial review
- incentivizes lumping changes together into one bigger PR
- new contributors don't know what length of delay is normal
- current review model favors a 1-reviewer-to-1-author model (1 assignee). Some PRs can be rather large, complex and/or spans multiple areas (especially cross-team responsibility). It might be beneficial to support multiple reviewers and allow each reviewer to say that they are happy with a subset of the changes proposed in the PR
- E.g. imagine if some PR touches compiler (name resolution, codegen) and libs, it might make sense to request a review from people who know the relevant parts well and has the suitable scope: `r? t_compiler_reviewer_1, t_compiler_reviewer_2, t_libs_reviewer`, a T-compiler reviewer for the name resolution, another for the codegen, and a T-libs reviewer for the libs part.
- UX unclear, not sure if desirable
- we have a significant lack of docs for a lot of things: high-level compiler docs, high-level compiler crate docs, important functions, key types, etc. (Understandably, *docs are very hard to write well*)
- between ci -> bootstrap -> compiletest -> individual test suites, we have *so many* undocumented explicit and implicit dependencies, flags, env vars and other quirks that make it very difficult to debug or understand.
- even if someone has the time and motivation to work on improving (internal, external) docs, they might not have the requisite knowledge -- who do they talk to? who do they ask?
- for new contributors: what support materials / references might be helpful to understanding a portion of the codebase?

## working on new features

- Call for Testing AFAICT is burried in *This Week in Rust* (TWiR) posts: many people (contributors, stakeholders of the feature being tested) don't read TWiR
- We probably really should coordinate r-l blog posts for Call for Testing, and promote them on relevant community platforms. Including context on what feature is being tested and relevant discussions could be very helpful.

## abandoned work

- teams don't check on subteams
- wg-embedded is basically not in the org, regardless of formal structure, because we don't talk to it regularly
- wg-devtools is super loosly-connected
- tracking issues get abandoned
- permissions issues
- people do work without recording it
- author stops working on it and no one else picks it up
- PRs don't get reviewed
- PRs get abandoned
- drives people to feeling *they personally* have to be the one to land work
- rustc-dev-guide [added S-inactive as a suggestion](https://github.com/rust-lang/rustc-dev-guide/pull/1977) but this is [not actually actionable](https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/Label.20closed.20PRs.20that.20lacked.20autor.20bandwidth/near/438975304)

## coordinating work is hard

- even coordinating these notes is hard!
- unclear when a claimed issue should be reassigned
- unclear when a PR should be closed
- people don't often work together on projects
- maintainers don't often split up work in tracking issues ("implement the RFC" as a single checkbox)
- unclear how to inform everyone in the project
- [e-mail] i think is only useable by infra admins? and feels "heavy". and goes to spam also.
- not everyone is on zulip; not everyone is on discord; not everyone even reads the same zulip *streams*
- inside-rust is ok but most people don't read it and it requires infra team to stamp it
- unclear when to ping who (should some WG/PG/teams be pinged for certain issues/PRs?)
- a load of knowedge lives inside random hackmd's :)

## people feel disempowered

- focus on correctness means even small changes take a while to land
- sometimes reviewers ask for lots of follow-up changes instead of opening an issue
- *waves vaguely at infra team*
- teams repo is useful but locks down permissions for stuff that doesn't matter
- modifying any hosted service requires extremely elevated permissions, so testing changes to triagebot/crater is ~impossible
- It feels like a waste of time to even try to contribute to infra's codebases
- If you want to fix bugs that are causing operational issues, you can't. i.e. when crater or rustc-perf freezes, people outside infra don't even have logs to debug from.
- Testing these codebases is either impossible or unreasonably difficult. We don't have a staging environment, or reliable instructions for standing up your own instance (I tried to stand up my own rustc-perf and failed)
- small teams literally cannot get changes reviewed unless someone outside the team opens the PR
- reference, most libs crates
- members of the rust project are discouraged from merging their own documentation PRs
- some documentation is better than no documentation! especially for internal docs

## workflow papercuts

- bors is broken and buggy and everyone knows it
- giant shoutout to @kobzol for working on this
- PRs pass CI and then fail in full bors run
- we could encourage / make more visible using arbitrary try builds for "likely to fail" CI jobs (again thanks @kobzol for working on this)
- weird target-specific failures are hard to replicate locally
- being able to run them in CI is useful, but sometimes not enough
- bootstrap is still confusing after all these years :(
- several people asked me (jyn) how it worked at rustNL
- using a different tool than cargo at all is annoying
- How can other contributors help? Are there any high-level design discussions?
- lots of project-specific infra that's annoying to learn
- labels
- triagebot, rfc bot, bors
- modifying integration between the compiler and standard library is massively frustrating
- [the bootstrap redesign](https://github.com/rust-lang/compiler-team/issues/619) would address this
- full builds are very slow
- modifying stage0 std rebuilds the world
- rebasing destroys your build cache
- the bootstrap redesign would kinda help with this
- new contributors don't know not to rebase
- feels like a Problem that people find it necessary to buy fancy computers just to work on rustc
- dev-desktops help but don't fully solve this
- distributed build caches would be so nice ...
- incremental builds are distractingly slow
- probably there is low-hanging fruit here WRT the query cache?
- RA is usually broken
- the fix is [just use rust-project.json](https://this.pr.is.fckn.gay/120611)
- rustc uses absurd amounts of disk space
- coming back to an old checkout after ~months is extremely prone to breaking
- people often just delete and recreate their clone
- force-pushing PRs destroys context and makes it hard to understand how a change evolved
- Recommend not to force push while reviewing, then once review is finished say "please make the commits pretty"?
- we should just fix `@bors squash` imo - @jyn514
- Submodule juggling sucks
- Bootstrap mostly works it out, but not always
- Leave your local repo for a few weeks? Sometimes it is just broken and nuking your local repo is the only sane option of fixing it
- It is not uncommon for someone to push a PR that accidentally updates a submodule
- Subtrees are better, but not a complete win
- The best solution I've seen is [Josh (Just One Single History)](https://github.com/josh-project/josh), which [Miri](https://github.com/rust-lang/miri/blob/master/CONTRIBUTING.md#advanced-topic-syncing-with-the-rustc-repo) and [Rust-Analyzer](https://github.com/rust-lang/rust-analyzer/pull/17025) use
- [HackMD for migrating to Josh](https://hackmd.io/7pOuxnkdQDaL1Y1FQr65xg?view)
- Having projects in-tree, but being told not to actually edit them in-tree
- This mostly seems motivated by the issue of submodules suck.
- Once again, the solution I've seen work is Josh.
- Also motivated by "keeping rustc CI times low," with some projects running larger suites in their own CI
- Messing up a merge / rebase is *very* scary for new contributors because it probably pings 50 people and adds 50 labels via triagebot notifications -- could we maybe suppress triagebot pings if there are merge commits (the easier case)?
- `@bors r+` doesn't get picked up in the top-level comment when you send a "Approve" review in GitHub UI
- juggling a chain or tree of dependent PRs is painful
- especially bad when multiple people want to build on top of each others' work
- encourages cramming more stuff into one PR, making reviews harder
- maybe we can suggest https://github.com/getcord/spr or https://sapling-scm.com/docs/addons/reviewstack/ ?
- merge conflicts amplify the inconvenience of bors queue times
- if two PRs are obviously going to conflict, there's often nothing that can be done about it until one of them lands
- even more inconvenient for contributors who don't have permissions to reapply `r+` in simple cases, and have to wait for the reviewer or find someone else to do it
- in particular, people effectively can't make rollups unless they're part of the org

## establishing consensus

- MCPs are not final; RFCs drift; ACPs sit unlooked at; lang team uses a new process each month
- What's the process for if RFCs/MCPs/ACPs need to be modified/diverge due to newly surfaced concerns or information?
- unclear who is in the project / who is a decision maker
- selective enforcement of processes
- long review delay
- focus on correctness at all costs, even in contexts where reverting is easy

### RFCs/tracking issues suck

- exhausting
- difficult to coordinate across teams (in both directions)
- coordination issues make RFCs harder
- RFCs being hard causes coordination issues
- full of [context collapse](https://en.wikipedia.org/wiki/Context_collapse). this problem [has been mentioned before](https://manishearth.github.io/blog/2019/02/04/rust-governance-scaling-empathy/)
- lots of writing
- template doesn't usually fit
- github's "load more" BS
- makes threads hard to Ctrl+F through or read the context of comments in the middle, even with direct link
- [previous discussion](https://rust-lang.zulipchat.com/#narrow/stream/242791-t-infra/topic/Feedback.20for.20github/near/418875758)
- In the meantime can be workaround with a [github-no-more](https://addons.mozilla.org/en-US/firefox/addon/github-no-more/) firefox extension
- Github does not allow to hide multiple comments at once
- It's annoying to mark discussions as oftopic/resolved/etc
- Even if you do, they are still rendered individually & take space
- Also: no way to describe the specific reason why you hid them
- members outside the org can't update tracking issues
- discussion happens "offline" and never gets written down
- full of irrelevant backlinks
- especially dozens of duplicate backlinks from force-pushed commits
- but some backlinks are useful
- it is very hard to know whether feedback matters or can be ignored
- feedback from random people is often useful, but rarely blocking
- feedback from team members is important and needs to be addressed
- due to the linearity of discussion, it's hard to address feedback individually
- no one really knows the state of individual subdiscussions, it's only the last one that matters
- focus on using inline review comments helps
- you open an RFC, get a bunch of comments and now need to something. the actual amount of work you're supposed to do is manageable, but you feel overwhelmed and swamped in review comments. it is not clear which ones matter. it is not clear how to properly "dismiss" a comment that doesn't. it is unclear how to properly "address" a comment that does. GitHub's UI for inline comments works, but many people leave normal comments. addressing such comments of basically impossible to do. epage mentioned moving these comments over to inline comments and then collapsing them, this is one way to get past it and certainly helps, is more effort though and requires permission.

## gay things

jyn asked me to put gay things into a separate section so here it is:

- https://jyn.is.fckn.gay
- https://nora.is.fckn.gay
- https://this.pr.is.fckn.gay