-
-
Notifications
You must be signed in to change notification settings - Fork 2.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge remote-tracking branch 'upstream/master' into importerbackgroun…
…dtask * upstream/master: Fixed exception about missing custom css file (#7292) Update the templates for opening a new issue (#7321) Entitlements file Mac (#7317) Make CONTRIBUTING.md much shorter. Move long text to docs/contributing.md (#7293) Include Github-optimized screenshot into repository (#7318)
- Loading branch information
Showing
19 changed files
with
600 additions
and
251 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| blank_issues_enabled: false | ||
| contact_links: | ||
| - name: Help | ||
| url: https://discourse.jabref.org/c/help/ | ||
| about: Questions and requests for help are handled at https://discourse.jabref.org | ||
| - name: Feature requests | ||
| url: https://discourse.jabref.org/c/features/ | ||
| about: If you are missing an important feature? Let us know! |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,133 +1,16 @@ | ||
| # Contributing Guide | ||
| # Contributing | ||
|
|
||
| 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) | ||
| When contributing to this repository, please first discuss the change you wish to make via issue, | ||
| email, or any other method with the owners of this repository before making a change. | ||
|
|
||
| In case you are an instructor and want to use JabRef as software engineering example, please head to <https://devdocs.jabref.org/teaching>. | ||
| Support on code contribution is available at <https://devdocs.jabref.org/contributing>. | ||
| General overview on contributing is available at <https://contribute.jabref.org>. | ||
|
|
||
| ## Understanding the basics | ||
| ## Pull Request Process | ||
|
|
||
| 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://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace). | ||
| 1. Fork the JabRef into your GitHub account. | ||
| 2. Clone your forked repository on your local machine. | ||
| 2. **Create a new branch** (such as `fix-for-issue-121`). Be sure to create a **separate branch** for each improvement you implement. | ||
| 3. Do your work on the **new branch - not the master branch.** Refer to our [code howtos](https://devdocs.jabref.org/getting-into-the-code/code-howtos) if you have questions about your implementation. | ||
| 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). | ||
|
|
||
| ## 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. | ||
|
|
||
| #### Format of keyboard shortcuts | ||
|
|
||
| Example: `<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 `+` | ||
|
|
||
| ### 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. | ||
| We will periodically update the contributors list inside [`AUTHORS`](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`. | ||
|
|
||
| Please, **do not add yourself at JavaDoc's `@authors`**. | ||
| 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`. | ||
| In any case, describe the library at [external-libraries.md](external-libraries.md). | ||
| We need that information for our package maintainers (e.g., those of the [debian package](https://tracker.debian.org/pkg/jabref)). | ||
| 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. | ||
| 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 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> | ||
| and neglected <other options>, | ||
| to achieve <system qualities/desired consequences>, | ||
| 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 | ||
| [ | ||
| 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](http://translate.jabref.org/) 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](https://devdocs.jabref.org/getting-into-the-code/code-howtos#using-localization-correctly). | ||
|
|
||
| ## Create a pull request | ||
|
|
||
| Create a pull request on GitHub following GitHub's guide "[Creating a pull request from a fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)". | ||
| For text inspirations, consider [How to write the perfect pull request](https://github.com/blog/1943-how-to-write-the-perfect-pull-request). | ||
|
|
||
| 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 | ||
| 1. Understand the basics listed at <https://devdocs.jabref.org/contributing>. | ||
| 2. Follow the "formal requirements". They are not too hard, they merely support the maintainers to focus on supportive feedback than just stating the obvious. The also have helpful hints how to work with localization. | ||
| 3. Create a pull request. You can create a draft pull request to enable automatic checks. | ||
| 4. Wait for feedback of the developers | ||
| 5. Address the feedback of the developers | ||
| 6. After two developers gave their green flag, the pull request will be merged. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
Oops, something went wrong.