Contributing — cljdoc 0.0.1315-c9e9a7e

Contributing to cljdoc

Hello there :wave: — 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.

To get the code up and running take a look at Running cljdoc locally.

Code of Conduct

cljdoc has adopted a Code of Conduct. Please read and adhere to it.

Reporting Bugs & Issues

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

Ways to contribute

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.

Code / Programming

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 Running cljdoc locally.

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.

Fixing Builds

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.

Outreach

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
…

Issue Specification / Design Work

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 valueable to the project regardless of your past experience with cljdoc specifically.

Why Contribute

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)

Maintainer’s Playbook

Becoming a Maintainer

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.

Merging PRs

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.

(Architecture) Decision Records

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.

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 :slightly_smiling_face:.

It may also be worth documenting decisions outside of software architecture.

Evaluating What To Work On

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:
1. cost of writing the code
2. cost of educating users about a feature
3. 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.

Thoughts?

This document is a work in progress, if you see any issues with it or have suggestions how to improve the cljdoc contributing experience, please open an issue or start a discussion on Slack.