Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

lint CONTRIBUTING.md #5473

Merged
merged 1 commit into from
Oct 17, 2019
Merged

lint CONTRIBUTING.md #5473

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 5 additions & 15 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

After reading through this guide, check out some good first issues to contribute to by clicking here: [Good First Issues](https://github.com/JabRef/jabref/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)


## Understanding the basics

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](https://guides.github.com/introduction/flow/index.html) and the explanation of [Feature Branch Workflow](https://atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow) for the idea behind this kind of development.

1. 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](https://github.com/JabRef/jabref/wiki/Guidelines-for-setting-up-a-local-workspace).
1. Fork the JabRef into your GitHub account.
2. Clone your forked repository on your local machine.
Expand All @@ -14,22 +14,20 @@ We welcome contributions to JabRef and encourage you to follow the GitHub workfl
4. Create a pull request. For an overview of pull requests, take a look at GitHub's [pull request help documentation](https://help.github.com/articles/about-pull-requests/).
5. In case your pull request is not yet complete or not yet ready for review, consider creating a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) instead.

In case you have any questions, do not hesitate to write one of our [JabRef developers](https://github.com/orgs/JabRef/teams/developers) an email. We should also be online at [gitter](https://gitter.im/JabRef/jabref).

In case you have any questions, do not hesitate to write one of our [JabRef developers](https://github.com/orgs/JabRef/teams/developers) an email.
We should also be online at [gitter](https://gitter.im/JabRef/jabref).

## 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.


### Add your change to CHANGELOG.md

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


#### Key format

Example: `<kbd>Ctrl</kbd> + <kbd>Enter</kbd>`
Expand All @@ -41,7 +39,6 @@ In case you add keys to the changelog, please follow these rules:
- Combined keys separated by `+`
- Spaces before and after separator `+`


### Author credits

You will be given credit in the [`AUTHORS`](AUTHORS) file in the root of the repository and the 'About' pages inside the main application.
Expand All @@ -58,21 +55,18 @@ The contribution information is tracked via the version control system.

Your contribution is considered being made under [MIT license](https://tldrlegal.com/license/mit-license).


### Write a good commit message

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.


### Test your code

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.


### When adding a library

Please try to use a version available at jCenter and add it to `build.gradle`.
Expand All @@ -82,7 +76,6 @@ 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 major code rewrites, we ask you to document your decision.
Expand All @@ -92,7 +85,7 @@ We simply ask to create a new markdown file in `docs/adr` following the template

In case you want to directly add a comment to a class, simply use following template (based on [sustainable architectural decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions)):

```
```text
In the context of <use case/user story u>,
facing <concern c>
we decided for <option o>
Expand All @@ -102,15 +95,14 @@ accepting <downside / undesired consequences>,
because <additional rationale>.
```


### When adding a new Localization.lang entry

Add new `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.

Example:

```
```text
java.lang.AssertionError: DETECTED LANGUAGE KEYS WHICH ARE NOT IN THE ENGLISH LANGUAGE FILE
PASTE THESE INTO THE ENGLISH LANGUAGE FILE
[
Expand All @@ -127,7 +119,6 @@ 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 Wiki](https://github.com/JabRef/jabref/wiki/Code-Howtos#using-localization-correctly).


### Create a pull request

Create a pull request on GitHub.
Expand All @@ -136,6 +127,5 @@ For text inspirations, consider [How to write the perfect pull request](https://
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](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
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.


[commit guidelines section of Pro Git]: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines
[good commit message]: https://github.com/joelparkerhenderson/git_commit_message