Hello there 👋 — nice to have you here. This document is designed to make your experience contributing to cljdoc nice and painless.
TLDR: We want to encourage as many people as possible to contribute to cljdoc in order for the project to properly become community-owned & operated. To achieve this the culture around cljdoc should always be welcoming to first time contributors, even if it sometimes means more work for existing maintainers.
|
Note
|
To get the code up and running take a look at the cljdoc Developer Technical Guide. |
cljdoc has adopted a Code of Conduct. Please read and adhere to it.
Use Slack or open an issue on GitHub.
Both are equally welcome. Slack may have slightly faster response times but if you really found a bug we’ll likely ask you to create an issue anyways :)
Slack: Go to http://clojurians.net and join the Clojurians Slack
team. You can then join the #cljdoc channel and report problems
or ask questions.
GitHub: cljdoc on GitHub
There are many ways you can contribute. While code is the most obvious contribution there are many other ways you can contribute that will be equally impactful on the project.
cljdoc is software and so a core component of creating it is writing code. If you want to contribute this way, take a look at the list of issues labelled "Good First Issue" and see if something is interesting to you or matches your experience.
To get up and running take a look at the cljdoc Developer Technical Guide.
Mentoring is available via the Slack group mentioned above and can also be done in a more private manner (private messages or video chat).
The "Good First Issue"s are often small and may not be the most rewarding in the long run but they are designed to get you up and running and make a meaningful change to cljdoc as soon as possible.
Once you feel more comfortable navigating the codebase everyone is welcome to push their own ideas or take on larger projects.
cljdoc runs some code for each documentation build (watch a few minutes of this talk if that is unfamiliar) and there are various reasons this code can fail.
Most of the time dependencies are missing or imporperly specified but there are other reasons too. This kind if issue prevents cljdoc from providing documentation for a project and that’s not nice.
So by invistigating a failing build and opening a pull request to the respective project you help to get more and more of the Clojure/Script ecosystem documented on cljdoc.
There is a full guide on fixing builds available.
cljdoc is for the Clojure and ClojureScript community. In order to provide value people first need to know that it even exists and what it is all about.
In the past I (Martin) have often noticed how things I thought I talked about a lot were still poorly understood by some of the people I met. And that’s not their fault. Everyone needs a different impulse for things to "click" and I hope that by more people talking about cljdoc and advocating for it we can send out a more diverse set of impulses.
So if you only have a few minutes to spare, consider the following actions:
-
tweet about cljdoc
-
open a PR to add a badge to a project that you like or use
-
write a blogpost
-
give a talk about it at your local meetup
-
post links to documentation in your company’s chat
-
refer people to cljdoc when appropriate
-
…
Often interesting ideas come up that require some more thought or design work before being ready to be worked on. The better the cljdoc community manages to specify issues the easier it will be for new and existing contributors to implement them.
Poorly specified issues lead to frustration because work might be done in a direction that was not intended, redundant or otherwise problematic.
Contributing this way is probably harder for newcomers but as people become more familiar with cljdoc they should be able to collectively hash out the details of new features.
Sometimes however the perspective of a relative newcomer can be especially useful and so if you like thinking about user experience or documentation in general your perspective might be valuable to the project regardless of your past experience with cljdoc specifically.
-
Warm fuzzy feelings of contributing to a project that benefits everyone using Clojure and ClojureScript.
-
Mentoring, code reviews and pairing sessions with experienced Clojure developers that can help you learn and master Clojure.
-
Some nice die-cut Stickers. (Send your address to Martin)
Contributors will be given write-access to the main cljdoc repository as soon as their first contribution was merged. This assumes good intentions and is obviously revoked if abused.
After that you are welcome to close issues, merge PRs and so forth. The contributing guidelines documented here aim at creating a community of maintainers and regular contributors and so once you contributed you are explicitly invited to take over more responsibility as you please.
-
Contributions should generally be reviewed and merged as fast as possible.
-
No bikeshedding in commit reviews, if a reviewer thinks fruther non-functional changes are important they are invited to make them while merging instead of introducing another review/change cycle. (Ideally small changes like this are communicated to the original author in the process.)
-
Once a user has contributed one commit they will become a maintainer as described above.
Sometimes little things make a big difference to other team members. Sometimes these little things might not be so obvious, hence this section.
-
Sometimes having multiple commits can make it easier to review a change.
-
After a first review, only append commits so reviewers can see what exactly changed.
-
Use GitHub’s keywords to close and refer to relevant issues from your commits.
-
Potential squashing and rebasing are responsibility of the maintainer merging the PR.
-
Small PRs are easier to review than large PRs. If a PR includes lots of changes multiple commits become critical to enable a proper review by maintainers.
In any project like this people make decisions that sometimes confuse others later on. Sometimes this is because a constraint that was previously present is no longer there. Sometimes it is better options becoming available or something else entirely.
In order to avoid such confusion cljdoc uses Architecture Decision Records
to document important* decisions. You can find these in doc/adr/ and are
invited to write ADRs as well.
|
Note
|
What’s important? There’s no easy or perfect answer here, one thing I often do is asking myself if the decision can be easily reverted later on. If it can, then an ADR might not be necessary — but could still be useful. When in doubt, just discuss with other contributors 🙂. |
It may also be worth documenting decisions outside of software architecture.
Our time is limited and bigger features should always be evaluated by the impact they will have on the project and the overall community.
Some thoughts which may help to decide what to work on:
-
cljdoc’s impact could be measured as the productivity boost it gives to Clojure/Script developers using it. Obviously this is hard to actually measure but it’s a good foundational assumption.
-
Initially cljdoc boosted that productivity by providing API documentation for libraries without requiring any extra work from library authors.
-
Each productivity boost comes with costs:
-
cost of writing the code
-
cost of educating users about a feature
-
cost of using a feature (e.g. library authors having to opt-in to something) - Some costs can be thought of as one-time whereas others may be recurring, e.g. incurring each time a library author opts-in to the feature.
-
Good features:
-
impact scales with the number of users,
-
while educating users about the feature is easy and
-
costs are mostly one-time.