.. _contributing: Contributing ============ 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 Codeberg. NOTE! Due to bugs in the GitLab -> Codeberg migration tool, old issues before October 2024 can only be found in the old [GitLab issue tracker](https://gitlab.com/jaywink/socialhome/-/issues). Logging issues -------------- 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. :ref:`reporting-security-issues` Writing code ------------ 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 :ref:`community` pages. Creating pull requests ---------------------- Before submitting a pull request, please ensure you've read and understood the following checklist. .. include:: PULL_REQUEST_TEMPLATE.txt Reviewing code -------------- 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 pull 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. Tests ----- 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. Testing tools ............. We use ``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. Code style ---------- Python ...... As a general rule, for Python code follow PEP8, except with a 120 character line length. We provide an ``.editorconfig`` in the repository root. JavaScript .......... There is an ``.eslintrc`` configuration provided. Alphabetical ordering ..................... 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. Python dependencies ------------------- .. include:: includes/pip_tools.rst