Contributing to Practicalli

Practicalli Kanban board - GitHub Project

Practicalli welcomes ideas and constructive feedback for content. Please reach out to the Practicalli team before making a contribution to avoid disappointment.

All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.

By submitting content ideas and corrections you are to that work becoming the copyright of Practicalli and published under the Creative Commons Attribution ShareAlike 4.0 International license. Attribution will be detailed via GitHub contributors, pull request and issue history.

Reaching out to the Practicalli Team before creating a pull request

Raise an issue, start a GitHub discussion or post a message on the #practicalli channel of Clojurians Slack community to avoid disappointment.

Content Tools

Practicalli books and websites are written in markdown and uses Material for MkDocs to generate the published website via a GitHub workflow. MkDocs can also run a local server using the make docs target from the Makefile

The README.md of each project contains install instructions for a local MkDocs server.

Submit and issue or idea

Each website and book has a link to its GitHub repository in the top-level navigation bar.

Use the Practicalli Kanban board to create an issue on any of the Practicalli GitHub repositories.

Considering a Pull request?

Pull Request Commits must be cryptographically signed

All commits contributed to Practicalli must be signed via a legitimate SSH or GPG key to avoid the risk of commit spoofing.

Configure commit signing with SSH key - Practicalli Engineering

All pull requests must include an entry in CHANGELOG.md or will not be merged. A changelog entry allows the community to follow the changes.

Each pull request will have a number of CI workflows run against the contribution, checking the format of the content and if a changelog entry has been provided.

Please keep pull requests small and focused, as they are much quicker to review and easier to accept. Ideally PR's should be for a specific page or at most a section.

A PR with a list of changes across different sections will be closed without merging as these take considerable time to review.

Issues such as grammar improvements are typically a sign of a rushed section that requires a rewrite, so a pull request to fix a typeographic error will probably not be merged. Raise an issue, or post a thread in the Clojurians Slack #practicall channel

Thank you to everyone that has contributed

A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language.

The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions. I would also like to thank everyone that has joined in with the London Clojurins community, ClojureBridgeLondon, Clojurians Slack community, Clojurians Zulip community and Clojureverse community.

Thank you to everyone who sponsors the Practicalli websites and videos and for the Clojurists Together sponsorship, it helps me continue the work at a much faster pace.

Special thanks to Bruce Durling for getting me into Cloure in the first place.