Want to contribute to Socialhome? Great! <3 Please read on for some guidelines.
First things first¶
Please make sure you have some knowledge of what the software is for before jumping in to write code. You don’t even have to install a development environment. Just head to https://socialhome.network, create an account and play around.
If you already are a user or run your own instance, you probably have some ideas on how to contribute already. The best contributions come from real personal need.
Finding things to do¶
We have an issue tracker on GitHub. If you don’t already have an idea on what to do, check out the issues listed there. Some issues are labeled as newcomer. These are easy picking tasks for those either new to Socialhome or with less knowledge of Django.
Contributions are not just code. Please feel free to log not only bugs but also enhancement ideas in the issue tracker. For issues that have not been confirmed (= they don’t have the label “ready”), triaging is important contribution also. Reproducing and supplying more information on these issues is valuable contributon to the project.
So you’re ready to write code! Great! Please remember though that the project already has a vision, the software has architecture and the project maintainer will have strong opinions on how things should be implemented. Before you write a lot of code that even remotely feels like it would need a design decision, please always discuss your plan first with the project maintainer. Otherwise you might spend a lot of time writing code only to be told the code will not be merged because it doesn’t fit into the grand plan.
Please don’t be afraid to get in touch, see channels in the Community pages.
Creating pull requests¶
Before submitting a pull request, please ensure you’ve read and understood the following checklist.
⚠ Please review the guidelines for contributing (https://socialhome.readthedocs.io/en/latest/contributing.html) to this repository and then go through the following checklist.
- Make sure you are requesting to merge a non-master branch from your fork. Do not create PR’s from your master branch!
- Does your code have unit tests? All major code paths should be tested sufficiently. See existing tests for examples.
- Did you run the whole test suite through and ensure no existing tests break?
- Please check the documentation whether your PR will require changes or additions to any documentation pages. Use proper English!
- If changing or adding UI pages or elements add screenshots to the PR.
- If the PR is not ready to be merged:
- Prefix the PR title with “[WIP] “.
- Add a list of TODO’s that are missing from the PR to the description.
- Consider adding a changelog entry to the current unreleased version. Use proper English, reference the right issue (if any, not your PR) and make sure to add the entry to the correct section (“Added”, “Changed”, “Fixed” or “Removed”). If you are not sure whether you need a changelog entry - don’t add one!
- Ensure commit messages are descriptive and sufficiently detailed. If possible, split the feature into smaller easier to follow commits. As a rule of thumb, small PR’s and small commits are always preferred. See https://chris.beams.io/posts/git-commit/ for notes on what is a good commit.
Thank you! ✌
Code review is a valuable way to contribute, and also to learn about the code base! Don’t be afraid to give some comments to open merge requests! You don’t have to be a veteran or know everything to be able to give opinions. Pull request reviews are not just for reviewing, they’re a valuable opportunity for learning too.
As a general rule all code must have unit tests. For bug fixes provide a test that ensures the bug will not be back and for features always add a good enough coverage. PR’s without sufficient test coverage will not be merged.
py.test as test runner but the tests themselves are Django based test classes. We have our own base classes which should be used as a base for all Django tests. Some old tests are pure py.test function based tests, feel free to convert these to Django test classes.
Focus is placed in pure unit tests instead of complex integration or browser tests. In terms of coverage, 100% is not the key, meaningful tests and coverage of critical lines is. Don’t worry if a PR drops coverage a bit if the coverage diff clearly shows all critical code paths are covered by meaningful tests.
As a general rule, for Python code follow PEP8, except with a 120 character line length. We provide an
.editorconfig in the repository root.
There is an
.eslintrc configuration provided.
When possible, try to always make all list items, dict keys, class methods, classes / functions in file, etc, everything alphabetically organized. This helps finding things when files grow and classes get a lot of methods. Sometimes this is not possible, for example when classes subclass another class in the same file. In this case for example, alphabetical ordering can be forgotten for logical placement.
pip-tools as the way to install Python dependencies. All the “base” dependencies, including production deployment dependencies are locked in
requirements.txt. The file
dev-requirements.txt includes both the base and the extra development/testing related dependencies.
pip-tools, first install it:
# Ensure pip and setuptools are up to date as well pip install -U pip pip-tools
Then install dependencies:
# Production environment pip-sync # Development environment pip-sync dev-requirements.txt
It is not mandatory to use
pip-tools for running a production installation. For development it is mandatory. All dependencies should be placed (unlocked) in either
requirements/requirements.in (base) or
requirements/requirements-dev.in (development extras). Then execute
./compile-requirements.sh to update the locked dependency files after each change to the
.in files. See pip-tools for more information.