Solvedjulia Taking Juleps seriously

c42f
147

For a while now I've felt that we could do better in documenting how pieces of the julia system come to be like they are. I do love that Julia runs on a "show me the code" philosophy, but this doesn't scale to big changes and many contributors. Here are some problems I've observed:

  • The outcome of long design discussion threads is rarely summarized, with the initial issue description containing only the starting point. People have to read through the entire discussion to understand the final design.
  • New contributors have little context for the larger design decisions made in the language. Instead, they have to sift a somewhat unstructured pile of github issues, commit messages and code to extract the buried wisdom. This leads to confusion and wasted effort.
  • Core contributors become a bottleneck in sharing design direction. This leads to frustration as less experienced developers become blocked, and can be an inefficient use of core contributor's time. Better design docs provide a scalable one-to-many solution to this issue.
  • Knowledge about design rationale is lost over time as people move on. A curated repository of design documentation helps avoid this problem. For example, Python's PEP documentation is a fantastic resource. Not just to the Python community, but to everyone interested in related problems in programming language design.

In my experience, the Juleps repository has not been successful in stimulating design discussion, and in any case is too heavyweight for initial triage of an idea and for many small changes. In contrast, the main JuliaLang/julia repository issue tracker has been a good venue for discussion, but is a poor place to curate design documentation for the longer term.

I've recently discovered the golang proposals repository, and I'd like to propose that we adopt something similar to their process:

  1. A julep starts life as a short description in JuliaLang/julia issue tracker.
  2. It is discussed with the aim to either accept, decline or ask for a full design document. If accepted or declined, the process stops.
  3. If a full design document is desired, the author writes it in the Juleps repository and works to address any issues brought up in the initial discussion. Feedback continues on the original issue.
  4. Once the comments and revisions wind down there's a final discussion where the proposal is accepted or rejected.

The intent is to keep our low overhead informal process in the github issues, but to preserve the hard work of design in a more digestible form, regardless of whether it is ultimately accepted or rejected.

36 Answers

✔️Accepted Answer

tkf
60

Sometimes it is rather disappointing to see the triage misses the important points in the discussion. Please don't take this as me blaming that the people involved in the triage. It is totally understandable that it is hard to pick up the main points to be discussed from a long thread like this. I think I've seen similar examples, not just this one.

Maybe this is where a lightweight systematic approach can help? For example, instead of marking an issue/PR with the triage tag, core devs can use a tag (say) summary requested for a long discussion (especially when it is unclear what to be discussed). Then the author of the issue/PR (or somebody else interested in the discussion) can write up a short summary of the discussion so far. Ideally it should list a few questions and points that need to be decided. I think it would help the triage to focus on important points. It also plays a somewhat overlapping role with Julep in that it provides the latest snapshot of the proposal.

Other Answers:

I'm only about 25% joking when I suggest that these should be titled:

  • Taking X seriously.

Consider:

  • Taking Structured Concurrency Seriously
  • Taking File Paths Seriously
  • Taking String Formatting Seriously

These are good names that are clear on what they are about.
We have precident.

My goodness do we ever take vector transposes seriously

I'm all for calling them "Taking X Seriously"—that's why I called this "Taking Juleps Seriously" 😃

I fully support a better documented process and I think it'd be helpful to hear from core devs what the best process is for proposing changes and getting things reviewed. Having recently gone through #32799, #32448, and with #32706 and #32859 still open, the experience has honestly been pretty frustrating. Proposing/submitting a change to Base now feels like at least a several-week process, with lots of pinging people, bumping PRs, waiting on answers to questions, pinging people privately, and eventually just threatening to merge, which has felt like the only way to actually get people to review. Now I totally understand the constraints on people's time, and I fight with managing that myself with a number of packages. I just think my frustration should still be voiced as I don't think my recent experience is mine alone; I'm not sure what could be done better, but ideally, people aren't unmotivated to contribute to Base due to the burden of the process.

I think what is quite common is that someone reviews a PR, it looks pretty good but perhaps a few things could be improved. The reviewer will give these potential improvements in the review and then leave the PR. The author is then left in a state where he/she is unsure about the state of the PR:

  • Can it be merged and the comments addressed at a later state?
  • Are the comments so important that it blocks the PR?
  • Are the questions posed in the review just questions and answering them is enough, or do I need to wait for a comment to my answer?

At this point, the reviewer might feel that he/she has done its job and might not return to the PR for a long time, while the author is still left wondering.

I, therefore, think that when reviewing and having comments that are such that the reviewer would block the PR from getting merged until they are fixed, the reviewer needs to properly indicate that. There is the "Changes requested" flag for reviews we could use for this or a label or something. A review that goes through without the "Changes requested" is considered ok to merge, even though the comments indicate that things could potentially be improved.

More Issues: