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 jrnl
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. If you're unsure what to change but still see a problem, you can open a new issue with the "Documentation change" type.
To edit the documentation, edit the docs/*.md files on the develop branch. You can see the result by running poe docs-run inside the project's root directory, then navigating your browser to localhost:8000.
If you'd like to share a jrnl command line trick that you find useful, you may find it worthwhile to add it to the "Tips and Tricks" section. For advice on how to integrate a particular external editor, you can add to the "External Editors" 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:
- being nimble
- having a simple interface
- avoiding 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 pyproject.toml. Users can run the commands by typing poe followed by the name of the command (Poe the Poet can be installed on its own, or as part of poetry install).
A typical development workflow includes:
- Installing dependencies:
poetry install
- Activate virtual environment:
poetry shell
- Running the source in a virtual environment:
jrnl(with or without arguments as necessary)
- Running tests:
poe test
- Formatting the code to standardize its style:
poe format
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 testing, jrnl uses pytest for unit tests, and pytest-bdd for integration testing. All tests are in the tests 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 tests/lib/ which are then executed by your tests in the feature files.
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:
You can also get a feel for the project's priorities by reviewing the milestones.
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!