Skip to content

Latest commit

 

History

History
117 lines (81 loc) · 5.39 KB

CONTRIBUTING.md

File metadata and controls

117 lines (81 loc) · 5.39 KB
Raw

Understanding the basics

We welcome contributions to JabRef and encourage to create a fork, clone, create a new branch (such as fix-for-issue-121), work on the new branch - not master, and create a pull request. Be sure to create a separate branch for each improvement you implement. Take a look at GitHub's excellent help documentation for a detailed explanation.

We also have guidelines for setting up a local workspace.

For newcomers, FLOSS Coach might be helpful. It contains steps to get started with JabRef development.

In case you have any questions, you can use our developers mailinglist.

Formal requirements for a pull request

The main goal of the formal requirements is to provide credit to you and to be able to understand the patch. Nevertheless we aim to keep the code consistently formatted, therefore we additionally have a requirement regarding the source formatter.

Ensure consistent formatting

Ensure your code is formatted according the JabRef formatting guidelines. These are provided as Eclipse formatting configuration in formatter_settings.xml. Ensure that JabRef's code cleanup settings are activated. Import cleanup_settings.xml. When you use Eclipse, the required config is generated automatically by gradlew eclipse. You can also run gradlew format to let the Gradle Format plugin do the formatting.

Add your change to CHANGELOG.md

You should edit the CHANGELOG.md 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.

Author credits

You will be given credit in the AUTHORS file in the root of the repository and the 'About' pages inside the main application. We will periodically update the contributors list inside AUTHORS. This is done by an automatic shell script scripts/generate-authors.sh.

If you want to add yourself directly with your pull request please run this script. Please make sure there are no duplicates or alternate spellings of your name listed. If you need to merge different Git usernames or email addresses you can do so by editing .mailmap. More information on this can be found via man git-shortlog.

Add yourself to the header

The headers of each .java file state the authors. These entries should match the modifications done. If you do not want to add your real name, add yourself as JabRef contributors.

For instance,

/*  Copyright (C) 2003-2011 JabRef contributors.

gets

/*  Copyright (C) 2003-2011 JabRef contributors.
 *  Copyright (C) 2015 Stefan Jauch

Please, do not add yourself at @authors. We have track this information in the header only.

Write a good commit message

See good commit message or commit guidelines section of Pro Git.

Test your code

We know that writing test cases causes 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 run gradlew check to ensure that your change doesn't break anything else.

When adding a library

Please try to use a version available at jCenter and add it to build.gradle. In any case, describe the library at external-libraries.txt. 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.

When making an architectural decision

In case you add a library or do mayor code rewrites, we ask you to document your decision. Recommended reading: http://www.infoq.com/articles/sustainable-architectural-design-decisions

Template:

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 d/undesired consequences>.
because <additional rationale>.

When adding a new Localization.lang entry

Run python scripts/syncLang.py -s to search for new untranslated strings. If everything is OK, run python scripts/syncLang.py -s -u to update JabRef_en.properties.

Create a pull request

Create a pull request on GitHub. For text inspirations, consider How to write the perfect pull request.

You can add the prefix [WIP] to indicate that the pull request is not yet complete, but you want to discuss something or inform about the current state of affairs.