We welcome contributions to jrnl, whether it's through reporting bugs, improving the documentation, testing releases, engaging in discussion on features and bugs, or writing code.
- Code of Conduct
- Reporting Bugs
- Editing Documentation
- Testing
- Submitting feature requests and ideas
- Developing
Before starting, please read the Code of Conduct.
Please report bugs by opening a new issue and describing it as well as possible. Many bugs are specific to a particular operating system and Python version, so please include that information!
If you find a typo or a mistake in the docs, please fix it right away and send a pull request.
To edit the documentation, edit the docs/*.md files on the develop branch. You can see the result if you run make html (or poetry run mkdocs serve if on Windows) inside the project's root directory, then navigating your browser to locahost:8000.
The gh-pages branch is automatically maintained and generated after your changes are merged. You should never have to edit that branch.
If you'd like to share a jrnl command line trick that you find useful, or advice on how to integrate a particular external editor, you may find it worthwile to add it to the "Recipes" section.
Much of the work of maintaining jrnl involves testing rather than coding.
The nature of jrnl means we deal with extremely sensitive data, and can't risk data loss. While jrnl does have a comprehensive automated testing suite, user testing is crucial to mitigating this risk.
Prereleases are deployed through PyPi much like normal releases. You can use pipx to fetch them and test them. See the changelog for information on what has changed with each release.
If you are comfortable enough with git, feel free to fetch particular pull requests, test them yourself, and report back your findings. Bonus points if you can add a screencast of how the new feature works.
There are always open bugs among our GitHub issues and many are specific to a particular OS, Python version, or jrnl version. A simple comment like "Confirmed on jrnl v2.2, MacOS 10.15, Python 3.8.1" would be extremely helpful in tracking down bugs.
See the develop section below for information on how to contribute new automated tests.
If you have a feature request or idea for jrnl, please open a new issue and describe the goal of the feature, and any relevant use cases. We'll discuss the issue with you, and decide if it's a good fit for the project.
When discussing new features, please keep in mind our design goals. jrnl strives to do one thing well. To us, that means:
- be slim
- have a simple interface
- avoid duplicating functionality
You will need to install poetry to develop jrnl. It will take care of all of the project's other dependencies.
jrnl uses two primary branches:
develop- for ongoing developmentrelease- for releases
In general, pull requests should be made on the develop branch.
You can find an inventory of commands in the makefile. *nix users can run the commands by typing make followed by the name of the command; however, Windows users will need to type out the commands directly, or install a third-party make tool such as GNU Make for Windows.
A typical development workflow includes:
- Running tests:
make test - Running the source in a virtual environment:
poetry installpoetry shelljrnl(with or without arguments as necessary)
- Linting the code to standardize its style:
make lint
When resolving bugs or adding new functionality, please add tests to prevent that functionality from breaking in the future. If you notice any functionality that isn't covered in the tests, feel free to submit a test-only pull request as well.
For integration testing, jrnl uses behave tests, which are all in the features folder.
Many tests can be created by only editing feature files with the same format as other tests. For more complicated functionality, you may need to implement steps in features/steps which are then executed by your tests in the feature files.
Starting in 2020, jrnl is also using pytest for unit tests. These tests are in the tests folder.
When you're ready, feel free to submit a pull request (PR). The jrnl maintainers generally review the pull requests every two weeks, but the continuous integration pipeline will run on automated tests on it within a matter of minutes and will report back any issues it has found with your code across a variety of environments.
The pull request template contains a checklist full of housekeeping items. Please fill them out as necessary when you submit.
If a pull request contains failing tests, it probably will not be reviewed, and it definitely will not be approved. However, if you need help resolving a failing test, please mention that in your PR.
You can search the jrnl GitHub issues by label for things to work on. Here are some labels worth searching:
Although jrnl has grown quite a bit since its inception, the overall complexity (for an end-user program) is fairly low, and we hope you'll find the code easy enough to understand.
If you have a question, please don't hesitate to ask! Python is known for its welcoming community and openness to novice programmers, so feel free to fork the code and play around with it! If you create something you want to share with us, please create a pull request. We never expect pull requests to be perfect, idiomatic, instantly mergeable code. We can work through it together!