Contributing to Racket

General
1

Hi,

Do we make it easy to contribute to Racket?

I've listed the resources I am aware of below.

Suggestions, PR's, comments, etc. all welcome! Help us make this better!

best wishes,
Stephen

Resources that new members of the community might find:

There is also Ways to contribute to Racket · racket/racket Wiki · GitHub which links to some of the above and covers other ways of contributing to the Racket Language, tools, project and community.

GitHub also links to https://github.com/racket/racket/blob/master/.github/CONTRIBUTING.md in the following places:

image
image876×535 92.3 KB

2 Likes
2

Stephen, many thanks for collecting all these different links! I hadn't thought there would be so many. :confused:

I can say, when I came to Racket, I got confused by all the different contribution documents, and I'm rather sure I had only found half of those you listed. Even if there are no contradictions, having so many different documents which might contradict each other can lead to paralysis. Even if you read all of these documents, I suppose you wouldn't be sure if you saw any contradictions. Even if information is merely duplicated, It's unnecessarily overwhelming.

Personally, I think it would be good to have one or at most two documents (not counting blog posts, which may be outdated, but kept for historical reasons) that collect what a contributor should know. I guess it's a good idea to separate the information according to the "type" of contribution (for example, fixing typos in the docs vs. working on the bootstrapping process), which I've seen in one of the documents. So people who want to get their feet wet don't need to read all the details relevant for major changes.

If we need/want more documents, there should be very good reasons for that and we should minimize overlap. By the way, one document doesn't necessarily mean one page. It could be several sections as in the docs (also listed by you).

3 Likes
3

For what it's worth, when I first started with Racket I found several places in the documentation where I wanted to contribute something -- an example, a typo fix, a clarification or additional content, etc. As a new contributor I found this effectively impossible since the literate programming nature of the documentation, the multiple repositories, and the unintuitive directory structure made it too hard to figure out where I should be making the change. A few times I settled for simply sending a suggestion to the list in hopes that someone more knowledgeable would add it, but that's a garbage way to do it as it imposes on other people's time. It was explained to me how to find the relevant bits but even with the explanation I found it too challenging and eventually gave up.

2 Likes
4

Hi @dstorrs , the issue of how to contribute to the documentation has come up in the past, and Greg suggested back in 2019 that the Racket Documentation is updated with links to the source repository (see this message: https://groups.google.com/g/racket-users/c/J8ylMGGGr-8/m/Ohhv6dLsBwAJ).

As a result of that suggestion, you can now click on any section heading on the Racket documentation, or the documentation for any Racket package, and a new box will show up with the direct link to the source repository scribble file:

image
image1093×567 49 KB

Alex.

6 Likes
5

That's brilliant. Thanks, Alex.

6

I agree with your observation.

I am comfortable with making small edits (typos etc) directly in the Github editor, but it takes an effort to improve the documentation otherwise.

As always it's a trade-off. Scribble brings a lot of quality-of-life features in the end product. Such as the killer feature: linking all identifiers to their documentation.

7

I would unfortunately say no. As an example, the top-level posts has 8 links, and that doesn't even cover them all, such as the build guide. The links are also spread out, where one is even a blog post.

I have also wanted many times to attempt to improve the documentation, but I never made it past directly editing in GitHub's web interface or suggesting improvements in a comment in a GitHub issue. Even then, I felt I had to prod a little to get those fixes in. I think that as long as there is not a clearly documented process on how to non-trivially edit the documentation, it will remain the case that only core people will be able to or will do it, but they are not the primary use case of someone finding documentation unclear, incorrect, or incomplete. I have been able to fix things in F#'s documentation rather straightforwardly.

One should also note that Racket is split across multiple repositories, and it seems to me that only the racket/racket repo gets what attention there is. Others, like maybe racket/gui, can be a bit of a ghost town in terms of activity and triage. I will say that Matthew Flatt has been very helpful fixing (non-trivial) issues, but he is obviously super busy, although he seems to be the main one showing up to fix things. I get the impression, whether it's real or not, that if he does not see an issue post and fix it, then it will basically go stale.

Lastly, I just don't see much activity on the issue pages from people knowledgeable on contributing. Maybe I should push through more, but I find it a bit intimidating both socially and technically, to contribute. I was even told once to basically not post in the issues on a bug report and instead ask questions on the mailing list, even for things that are bugs.

I was trying to go all in on Racket for a project, but I personally lost a lot of steam. With the above issues coupled with the complexity of the GUI toolkit, lack of clear documentation, and bugs in the toolkit, I just lost steam. Also, with Rhombus looming overhead, a question pops into mind asking if it's worth it to invest a lot of time in Racket.

4 Likes
8

What does F# do that makes it easy to contribute?
(Apart from being backed by Microsoft :rofl:)

Racket is a modern, influential language, that continues to improve both the language and the tooling. It is punching way above its weight. I’d go as far to say Racket is unquestionably the best lisp available today. It is the best language(s) for me. :party_blob_gif:

1 Like
9

Answering myself...

Would it be an idea to add a Github Action that builds automatically builds the documentation when a PR is submitted that only changes a .scrbl file?

After building the documentation the Gihub action could copy it to racket.github.io/repo/commit/index.html so the submitter can see if the change broke anything.

For Sketching I have added Github Actions that builds the documentation when a PR is made.
Right now, only if the PR is merged to main, the the resulting html pages are copied to Sketching A Language for Creative Coding

3 Likes
10

this went meta fast...

The lovely community over at p5.js use a special issue to help new contributors: https://github.com/processing/p5.js/issues/2865

So I shamelessly copied them https://github.com/racket/racket/issues/4130

best regards,

Stephen

PS Credit to @soegaard for bringing the p5.js issue to my attention.

11

This is kind of an odd reply to read in your own thread asking what makes it hard to contribute…

@bmitc listed various challenges they faced, which seems like good feedback to review for possible ways to improve. I don’t think just saying “Racket is the best” helps this particular conversation. :stuck_out_tongue_winking_eye:

1 Like
12

Hi,

I’m grateful for feedback on the challenges to contributing but I’m neither required, nor able to respond to them right now.

I’m interested in what can be done - the F# documentation was given as an example of ‘what good looks like’* and I absolutely want to know more.

I think it is fine to say how we feel. In response to feelings of doubt I responded that I feel confident and excited about Racket. I think you should feel that way too.

All the best

Stephen
:heart:

  • a recent catchphrase in my sector

PS Racket is absolutely a modern influential language with great tools. And a shiny new compiler. Vroom vroom. :racing_car:

13

Of course, I did not mean to imply you or anyone else is required to do something… :sweat_smile:

I meant it seems like good feedback for all of us to reflect on, and (for those who may have time) to think about what could be done to improve on issues they highlighted.

Replying with “Racket is the best” makes it seem like everything is great and we just need to like it more … personally I would feel like my feedback was dismissed with such a reply. :confused:

2 Likes
14

As for my own feedback, I agree with others here that at the moment, there are many documents (as indicated by the many links at the top of the thread), each of which covers different bits and pieces, so it can take quite a while before you feel like you have uncovered all the ingredients.

I think a good goal to strive for would be a single resource that covers various different Racket internals, including contribution of course. Rust's Guide to Rustc Development is a great example from another language ecosystem.

To take one specific example, at the moment I've been trying to understand Racket's bootstrapping process in more detail, such which modules are used in which stage, where the output of those connects to the next stage, etc. There are a few breadcrumbs spread across various README files in the source tree, but so far I don't have the full picture in my mind yet. Anyway, I'll try to write up my own notes as my understanding improves, and that could potentially be a part of some future resource on Racket internals.

3 Likes
15

What does F# do that makes it easy to contribute?

There are two things: (1) The system is less indirect, which makes it much easier to find the location of the documentation that you want to edit and also doesn't necessarily require building to see changes (see below), (2) Triaging of issues is usually more active and organized.

To edit documentation in the F# guide, such as the page for let Bindings, simply go to the top-right and select Edit. This takes you directly to the markdown in GitHub. Since that part of the documentation is in markdown, one can easily just use the GitHub web interface for editing and previewing markdown.

For reference documentation for modules, such as for the List Module, one can just click on the GitHub symbol next to a function, and it takes you to the implementation location. Simply change the file extension in the address bar from .fs to .fsi, and there you'll find the documentation, formatted as XML. Note that this also makes it very easy to find implementations of core functions.

(F# is actually not controlled by Microsoft but by the F# Software Foundation. I don't think there are many at Microsoft who are full-time F# developers/maintainers. F# does benefit from Microsoft and .NET infrastructure.)

1 Like
16

I would unfortunately say no. As an example, the top-level posts has 8 links, and that doesn’t even cover them all, such as the build guide. The links are also spread out, where one is even a blog post.

FWIW, among those 8 links, half of them are redundant, and probably should not be listed there in the first place.

  • “Building, Distributing, and Contributing to Racket” is the main one that I think is worth reading.
  • “Tutorial: Contributing to Racket” is a blog tutorial. It’s less comprehensive but more friendly, and includes the social process.
  • “racket/README.md at master · racket/racket” has no meaningful content. It essentially links to the first item (“Building, Distributing, and Contributing to Racket”)
  • “racket/build.md at master · racket/racket” is just a Markdown version of “Building, Distributing, and Contributing to Racket”.
  • “3 Contributing to Racket Development” is a subpage of “Building, Distributing, and Contributing to Racket”.
  • “Ways to contribute to Racket · racket/racket Wiki” is a portal page, with some orthogonal content on donation and concrete bugs to fix.
  • “https://github.com/racket/racket/blob/master/.github/CONTRIBUTING.md“ has no meaningful content. It essentially links to the first item (“Building, Distributing, and Contributing to Racket”)
  • “Contribute to racket/racket · GitHub” is a list of “good first issues” on GitHub.

So really, there are only 4 sources that are distinct enough to be worth mentioning:

  • The guide: “Building, Distributing, and Contributing to Racket”. This is the main one that should be read.

  • A tutorial: “Tutorial: Contributing to Racket”

  • A wiki page: “Ways to contribute to Racket · racket/racket Wiki”

  • A list of “good first issues”: “Contribute to racket/racket · GitHub”

Personally, I find these reasonable. They cover different aspects of the contribution guide, and they seem appropriate for their own medium. One possible improvement is to merge content from other sources as appropriate into the actual guide, stop referring to merged sources, and make the guide very verbose. I.e., include a lot of pictures and step-by-step instructions to make it very easy to follow.

Part of the issue, I think, is that we keep adding more stuff, rarely letting go of superseded content, perhaps because we think that more resources are better. But as this thread shows, this is not the case. It causes confusion, fragmentation, and makes people feel inundated with information sources.

I also agree that it’s difficult to contribute. I personally feel like a prerequisite for contribution to Racket is building Racket from source. But building from source is a big commitment, and long building time is a huge turn-off factor for most people.

6 Likes
17

Still, I find it interesting that this shows what a potential contributor encounters. You'll find all (or part of those) links with a web search, and before you've checked them out, you naturally won't know which of them are redundant and in which ways.

That said, I guess what shows up in a web search is mostly out of our control; we can only change the contents of these pages. I think it might help if the pages that repeat information from other pages would instead just link to these other pages. And if a page has additional content compared to the official documentation, maybe some of this additional information could be merged into the official documentation and being removed/linked from the page that contributed this additional information.

1 Like
18

Thank you @sorawee for doing the hard work of analysing the resources linked.

I think the appropriate action is a PR to change both README.md and build.md to remove the duplication and link to the definitive guide at https://docs.racket-lang.org/racket-build-guide/index.html

https://github.com/racket/racket/blob/master/README.md
https://github.com/racket/racket/blob/master/build.md

I’ll try make a PR later but I’d be happy if someone beat me to it.

Completely agree.

I think an advantage of the Racket Cookbooks project is to lower the barriers to contribution. This means you can still contribute if you lack the time* or confidence to build from source.

I agree this needs some work - I did a little yesterday but would be very happy for others to do the same. It is a wiki - anyone can edit and it is all markdown.

Best regards

Stephen

postscript

I was originally thinking of doing very clever things with dynamic-require and scribble but I rapidly realised that was going to take more time than I currently have :sob:.

19

Also, very clever things are often hard to understand by others and hard to maintain. :wink:

1 Like
20

It would be wonderful if someone would incorporate the material from Tutorial: Contributing to Racket into Building, Distributing, and Contributing to Racket .

I only happened to find the tutorial by searching for "build scribble" here on discord. The material in Building, Distributing, and Contributing to Racket is a bit opaque and omits the case where one wants to contribute to the non-core libraries hosted at the racket github repo.

1 Like