After reading through this guide, check out some good first issues to contribute to by clicking here: Good First Issues
In case you are aiming to contribute other improvements, please head over to our general JabRef contribution page.
In case you are an instructor and want to use JabRef as a software engineering example, please head to https://devdocs.jabref.org/teaching.
We welcome contributions to JabRef and encourage you to follow the GitHub workflow specified below. If you are not familiar with this type of workflow, take a look at GitHub’s excellent overview on the GitHub flow and the explanation of Feature Branch Workflow for the idea behind this kind of development.
- Get the JabRef code on your local machine. Detailed instructions about this step can be found in our guidelines for setting up a local workspace.
- Fork the JabRef into your GitHub account.
- Clone your forked repository on your local machine.
- Create a new branch (such as
fix-for-issue-121). Be sure to create a separate branch for each improvement you implement.
- Do your work on the new branch — not the
mainbranch. Refer to our code how-tos if you have questions about your implementation.
- Create a pull request. For an overview of pull requests, take a look at GitHub’s pull request help documentation.
- In case your pull request is not yet complete or not yet ready for review, consider creating a draft pull request instead.
The main goal of the formal requirements is to provide credit to you and to be able to understand the patch.
You should edit the
CHANGELOG.md file located in the root directory of the JabRef source. Add a line with your changes in the appropriate section.
If you did internal refactorings or improvements not visible to the user (e.g., UI, .bib file), then you don’t need to put an entry there.
<kbd>Ctrl</kbd> + <kbd>Enter</kbd>
In case you add keys to the changelog, please follow these rules:
<kbd>tag for each key
- First letter of key capitalized
- Combined keys separated by
- Spaces before and after separator
Please, do not add yourself at JavaDoc’s
@authors. The contribution information is tracked via the version control system and shown at https://github.com/JabRef/jabref/graphs/contributors. We also link to the contributors page in our about dialog.
Your contribution is considered being made under MIT license.
See good commit message or commit guidelines section of Pro Git. The first line of your commit message is automatically taken as the title for the pull-request. All other lines make up the body of the pull request. Add the words
fixes #xxx to your PR to auto-close the corresponding issue.
We know that writing test cases takes a lot of time. Nevertheless, we rely on our test cases to ensure that a bug fix or a feature implementation doesn’t break anything. In case you do not have time to add a test case, we nevertheless ask you to at least run
gradlew check to ensure that your change doesn’t break anything else.
Localization.lang("KEY") to a Java file. The tests will fail. In the test output a snippet is generated, which must be added to the English translation file.
java.lang.AssertionError: DETECTED LANGUAGE KEYS WHICH ARE NOT IN THE ENGLISH LANGUAGE FILE PASTE THESE INTO THE ENGLISH LANGUAGE FILE [ Opens\ JabRef's\ Twitter\ page=Opens JabRef's Twitter page ] Expected : Actual :[Opens\ JabRef's\ Twitter\ page (src\main\java\org\jabref\gui\JabRefFrame.java LANG)]
Add the above snippet to the English translation file located at
src/main/resources/l10n/JabRef_en.properties. Crowdin will automatically pick up the new string and add it to the other translations.
You can also directly run the specific test in your IDE. The test “LocalizationConsistencyTest” is placed under
src/test/java/net.sf.jabref.logic.l10n/LocalizationConsistencyTest.java. Find more information in the JabRef developer docs.
Please try to use a version available at JCenter and add it to
build.gradle. In any case, describe the library at
external-libraries.md. We need that information for our package maintainers (e.g., those of the debian package). Also add a txt file stating the license in
libraries/. It is used at
gradlew processResources to generate the About.html files. You can see the result in
build\resources\main\help\en\About.html or when clicking Help -> About.
In case you add a library or do major code rewrites, we ask you to document your decision. Recommended reading: https://adr.github.io/.
We simply ask to create a new markdown file in
docs/adr following the template presented at https://adr.github.io/madr/.
In case you want to directly add a comment to a class, simply use the following template (based on sustainable architectural decisions):
In the context of <use case/user story u>, facing <concern c> we decided for <option o> and neglected <other options>, to achieve <system qualities/desired consequences>, accepting <downside / undesired consequences>, because <additional rationale>.
If you want to indicate that a pull request is not yet complete before creating the pull request, you may consider creating a draft pull request. Alternatively, once the PR has been created, you can add the prefix
[WIP] (which stands for “Work in Progress”) to indicate that the pull request is not yet complete, but you want to discuss something or inform about the current state of affairs.
You can also host Jekyll locally.
docker run --rm -it \ --volume="$pwd:/srv/jekyll" \ jekyll/builder:latest /bin/bash -c "gem install && bundle exec jekyll build && bundle exec rake search:init && jekyll serve"
Then, you can see a near-to-reality rendering of the development documentation at http://localhost:4000.