# Contributing to Racket **URL:** \ **Category:** General\ **Created:** [January 10, 2022, 11:31am UTC](https://racket.discourse.group/t/contributing-to-racket/542 "2022-01-10T11:31:34Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![spdegabrielle](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/spdegabrielle/32/95_2.png) [@spdegabrielle](https://racket.discourse.group/u/spdegabrielle)\ **Post date:** [January 10, 2022, 11:31am UTC](https://racket.discourse.group/t/contributing-to-racket/542/1 "2022-01-10T11:31:34Z")
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: - [Building, Distributing, and Contributing to Racket](https://docs.racket-lang.org/racket-build-guide/index.html) (docs) - [Tutorial: Contributing to Racket](https://blog.racket-lang.org/2017/09/tutorial-contributing-to-racket.html) (Racket Blog) - [racket/README.md at master · racket/racket · GitHub](https://github.com/racket/racket/blob/master/README.md) has a contributing section, which links to... - [racket/build.md at master · racket/racket · GitHub](https://github.com/racket/racket/blob/master/build.md) - the home page also links to [3 Contributing to Racket Development](https://docs.racket-lang.org/racket-build-guide/contribute.html) There is also [Ways to contribute to Racket · racket/racket Wiki · GitHub](https://github.com/racket/racket/wiki/Ways-to-contribute-to-Racket) 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](https://github.com/racket/racket/blob/master/.github/CONTRIBUTING.md) in the following places: - [Contribute to racket/racket · GitHub](https://github.com/racket/racket/contribute) (I'm not sure how anyone finds this) - When you create a pull request as a tiny link on right - I'm not sure anyone has ever clicked this: ![image](https://global.discourse-cdn.com/free1/uploads/racket/original/1X/1fb914e1c44fb388c7bf7165c865d12a137ef774.png) ---
**Author:** ![sschwarzer](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/sschwarzer/32/1940_2.png) [@sschwarzer](https://racket.discourse.group/u/sschwarzer)\ **Post date:** [January 10, 2022, 10:47pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/2 "2022-01-10T22:47:30Z")
Stephen, many thanks for collecting all these different links! I hadn't thought there would be so many. 😕 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](https://docs.racket-lang.org/racket-build-guide/index.html) (also listed by you). ---
**Author:** ![dstorrs](https://avatars.discourse-cdn.com/v4/letter/d/898d66/32.png) [@dstorrs](https://racket.discourse.group/u/dstorrs)\ **Post date:** [January 11, 2022, 10:46pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/3 "2022-01-11T22:46:14Z")
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. ---
**Author:** ![alexh](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/alexh/32/315_2.png) [@alexh](https://racket.discourse.group/u/alexh)\ **Post date:** [January 11, 2022, 11:37pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/4 "2022-01-11T23:37:16Z")
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](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](https://global.discourse-cdn.com/free1/uploads/racket/original/1X/3bdfca8b183a3896753c0ca96b46cfb7e86bef7e.png) Alex. ---
**Author:** ![dstorrs](https://avatars.discourse-cdn.com/v4/letter/d/898d66/32.png) [@dstorrs](https://racket.discourse.group/u/dstorrs)\ **Post date:** [January 13, 2022, 4:40am UTC](https://racket.discourse.group/t/contributing-to-racket/542/5 "2022-01-13T04:40:28Z")
That's brilliant. Thanks, Alex. ---
**Author:** ![soegaard](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/soegaard/32/19_2.png) [@soegaard](https://racket.discourse.group/u/soegaard)\ **Post date:** [January 13, 2022, 7:01am UTC](https://racket.discourse.group/t/contributing-to-racket/542/6 "2022-01-13T07:01:43Z")
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. ---
**Author:** ![bmitc](https://avatars.discourse-cdn.com/v4/letter/b/46a35a/32.png) [@bmitc](https://racket.discourse.group/u/bmitc)\ **Post date:** [January 17, 2022, 5:26am UTC](https://racket.discourse.group/t/contributing-to-racket/542/7 "2022-01-17T05:26:18Z")
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. ---
**Author:** ![spdegabrielle](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/spdegabrielle/32/95_2.png) [@spdegabrielle](https://racket.discourse.group/u/spdegabrielle)\ **Post date:** [January 17, 2022, 8:14pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/8 "2022-01-17T20:14:11Z")
> [@bmitc](#): > > I have been able to fix things in F#'s documentation rather straightforwardly. **What does F# do that makes it easy to contribute?** (Apart from being backed by Microsoft 🤣) > [@bmitc](#): > > a question pops into mind asking if it's worth it to invest a lot of time in Racket. 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: ---
**Author:** ![soegaard](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/soegaard/32/19_2.png) [@soegaard](https://racket.discourse.group/u/soegaard)\ **Post date:** [January 17, 2022, 8:29pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/9 "2022-01-17T20:29:46Z")
> [@soegaard](#): > > 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. 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](http://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](http://soegaard.github.io/sketching/) ---
**Author:** ![spdegabrielle](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/spdegabrielle/32/95_2.png) [@spdegabrielle](https://racket.discourse.group/u/spdegabrielle)\ **Post date:** [January 17, 2022, 8:53pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/10 "2022-01-17T20:53:40Z")
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](https://github.com/processing/p5.js/issues/2865) So I shamelessly copied them [https://github.com/racket/racket/issues/4130](https://github.com/racket/racket/issues/4130) best regards, Stephen PS Credit to @soegaard for bringing the p5.js issue to my attention. ---
**Author:** ![jryans](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/jryans/32/31_2.png) [@jryans](https://racket.discourse.group/u/jryans)\ **Post date:** [January 17, 2022, 10:47pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/11 "2022-01-17T22:47:18Z")
> [@spdegabrielle](#): > > 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: 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. 😜 ---
**Author:** ![spdegabrielle](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/spdegabrielle/32/95_2.png) [@spdegabrielle](https://racket.discourse.group/u/spdegabrielle)\ **Post date:** [January 17, 2022, 11:59pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/12 "2022-01-17T23:59:05Z")
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 ❤ - a recent catchphrase in my sector PS Racket _is_ absolutely a modern influential language with great tools. And a shiny new compiler. Vroom vroom. 🏎 ---
**Author:** ![jryans](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/jryans/32/31_2.png) [@jryans](https://racket.discourse.group/u/jryans)\ **Post date:** [January 18, 2022, 1:04am UTC](https://racket.discourse.group/t/contributing-to-racket/542/13 "2022-01-18T01:04:09Z")
Of course, I did not mean to imply you or anyone else is required to do something… 😅 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. 😕 ---
**Author:** ![jryans](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/jryans/32/31_2.png) [@jryans](https://racket.discourse.group/u/jryans)\ **Post date:** [January 18, 2022, 1:22am UTC](https://racket.discourse.group/t/contributing-to-racket/542/14 "2022-01-18T01:22:48Z")
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](https://rustc-dev-guide.rust-lang.org/) 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. ---
**Author:** ![bmitc](https://avatars.discourse-cdn.com/v4/letter/b/46a35a/32.png) [@bmitc](https://racket.discourse.group/u/bmitc)\ **Post date:** [January 18, 2022, 2:04am UTC](https://racket.discourse.group/t/contributing-to-racket/542/15 "2022-01-18T02:04:13Z")
> **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](https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/functions/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](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-collections-listmodule.html), 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.) ---
**Author:** ![sorawee](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@sorawee](https://racket.discourse.group/u/sorawee)\ **Post date:** [January 18, 2022, 2:09am UTC](https://racket.discourse.group/t/contributing-to-racket/542/16 "2022-01-18T02:09:55Z")
> 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](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. ---
**Author:** ![sschwarzer](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/sschwarzer/32/1940_2.png) [@sschwarzer](https://racket.discourse.group/u/sschwarzer)\ **Post date:** [January 18, 2022, 11:49am UTC](https://racket.discourse.group/t/contributing-to-racket/542/17 "2022-01-18T11:49:27Z")
> [@sorawee](#): > > FWIW, among those 8 links, half of them are redundant, and probably should not be listed there in the first place. 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](https://docs.racket-lang.org/racket-build-guide/index.html), 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. ---
**Author:** ![spdegabrielle](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/spdegabrielle/32/95_2.png) [@spdegabrielle](https://racket.discourse.group/u/spdegabrielle)\ **Post date:** [January 18, 2022, 2:00pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/18 "2022-01-18T14:00:34Z")
Thank you @sorawee for doing the hard work of analysing the resources linked. > [@sorawee](#): > > “racket/build.md at master · racket/racket” is just a Markdown version of “Building, Distributing, and Contributing to Racket”. 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://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/README.md) [https://github.com/racket/racket/blob/master/build.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. > [@sorawee](#): > > 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. 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. > [@sorawee](#): > > “Ways to contribute to Racket · racket/racket Wiki” is a portal page, with some orthogonal content on donation and concrete bugs to fix. 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 😭. ---
**Author:** ![sschwarzer](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/sschwarzer/32/1940_2.png) [@sschwarzer](https://racket.discourse.group/u/sschwarzer)\ **Post date:** [January 18, 2022, 2:09pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/19 "2022-01-18T14:09:38Z")
> [@spdegabrielle](#): > > 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 😭. Also, _very clever things_ are often hard to understand by others and hard to maintain. 😉 ---
**Author:** ![stevebyan](https://avatars.discourse-cdn.com/v4/letter/s/e56c9b/32.png) [@stevebyan](https://racket.discourse.group/u/stevebyan)\ **Post date:** [July 13, 2024, 8:37pm UTC](https://racket.discourse.group/t/contributing-to-racket/542/20 "2024-07-13T20:37:22Z")
It would be wonderful if someone would incorporate the material from [Tutorial: Contributing to Racket](https://blog.racket-lang.org/2017/09/tutorial-contributing-to-racket.html) into [Building, Distributing, and Contributing to Racket](https://docs.racket-lang.org/racket-build-guide/index.html). I only happened to find the tutorial by searching for "build scribble" here on discord. The material in [Building, Distributing, and Contributing to Racket](https://docs.racket-lang.org/racket-build-guide/index.html) is a bit opaque and omits the case where one wants to contribute to the non-core libraries hosted at the racket github repo.