-
-
Notifications
You must be signed in to change notification settings - Fork 2.5k
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.
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
FAQ updates #11486
FAQ updates #11486
Conversation
docs/code-howtos/faq.md
Outdated
@@ -7,14 +7,32 @@ parent: Code Howtos | |||
|
|||
Following is a list of common errors encountered by developers which lead to failing tests, with their common solutions: | |||
|
|||
* Failing <b>Checkstyle</b> tests: | |||
* <span style="color:green">Fix</span> : JabRef follows a pre-defined style of code for uniformity and maintainabiltiy that must be adhered to during development. To set-up warnings and auto-fixes conforming to these style rules in your IDE, follow [Step 3](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/intellij-13-code-style.html) of the process to set up a local workspace in the documentation. Ideally, follow all the [set up rules](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/) in the documentation end-to-end to avoid typical set-up errors.<br> <b>Note</b>: The steps provided in the documentation are for IntelliJ, which is the preferred IDE for Java development. The ```checkstyle.xml``` is also available for VSCode, in the same directory as mentioned in the steps. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Remove the space after </span>
. Reason: A colon (":") is NOT proceeded by a space.
Do that for all other "Fix" things.
docs/code-howtos/faq.md
Outdated
* <span style="color:green">Fix</span> : JabRef follows a pre-defined style of code for uniformity and maintainabiltiy that must be adhered to during development. To set-up warnings and auto-fixes conforming to these style rules in your IDE, follow [Step 3](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/intellij-13-code-style.html) of the process to set up a local workspace in the documentation. Ideally, follow all the [set up rules](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/) in the documentation end-to-end to avoid typical set-up errors.<br> <b>Note</b>: The steps provided in the documentation are for IntelliJ, which is the preferred IDE for Java development. The ```checkstyle.xml``` is also available for VSCode, in the same directory as mentioned in the steps. | ||
|
||
* Failing <b>OpenRewrite</b> tests: | ||
* <span style="color:green">Fix</span> : [OpenRewrite](https://docs.openrewrite.org/) is an automated refactoring ecosystem for source code. Run ```gradle rewriteRun``` to apply the automated refactoring and pass the test. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do NOT write gradle XY
. Please write "execute gradle task rewriteRun
. And state in which group in IntelliJ it is.
Reason: The guidelines are written in a away that the contributors DO NOT have a JDK installed. Therefore, "gradlew" probably does not work. Since most fixing tasks work with IntelliJ's gradle window and do not require gradle in the command line, we should also have the FAQ answers working without an JDK outside of IntelliJ
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Moreover, use single backquotes; not triple ones. Triple are used for code blocks only.
docs/code-howtos/faq.md
Outdated
Read more about the background and format of localization in JabRef [here](https://devdocs.jabref.org/code-howtos/localization.html). | ||
|
||
* ```org.jabref.logic.l10n.LocalizationConsistencyTest``` ```findObsoleteLocalizationKeys``` <span style="color:red">FAILED</span> | ||
* <span style="color:green">Fix</span> : There are localization keys [localization properties file](https://github.com/JabRef/jabref/blob/main/src/main/resources/l10n/JabRef_en.properties) that are not used in the code, probably due to the removal of existing code. Navigate to the unused key-value pairs in the file and remove them. You can always click on the details of the failing test to pinpoint which keys are unused. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please link the localization howto here, too. - Impatient readers won't use the link of another bullet point.
docs/code-howtos/faq.md
Outdated
|
||
* ```java.lang.IllegalArgumentException``` : Unable to load locale en-US<br> <span style="color:red">ERROR: Could not generate BibEntry citation. The CSL engine could not create a preview for your item.</span> | ||
* <span style="color:green">Fix</span> : Check the directory ```src/main/resources/csl-locales```. If it is missing or empty, run ```git submodule update```. If still not fixed, run ```git reset --hard``` <b>inside that directory</b>. | ||
|
||
* `org.jabref.architecture.MainArchitectureTest` `restrictStandardStreams` <span style="color:red">FAILED</span> | ||
* <span style="color:green">Fix</span> : Check if you've used ```System.out.println(...)``` (the standard output stream) to log anything into the console. This is an architectural violation, as you should use the Logger instead for logging. More details on how to log can be found [here](https://devdocs.jabref.org/code-howtos/logging.html). | ||
|
||
* `org.jabref.architecture.MainArchitectureTest` `doNotUseLogicInModel` <span style="color:red">FAILED</span> | ||
* <span style="color:green">Fix</span> : One common case when this test fails is when you put any class purely containing business logic at some level inside the ```model``` directory (```org/jabref/model/```). To fix this, shift the class to a subdirectory within the ```logic``` directory (```org/jabref/logic/```). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Proposed addition in next update: |
* upstream/main: Fix NPE when saving preferences (JabRef#11509) Switch to stream-based loading (JabRef#11479) Save unlinked local files dialog prefs (JabRef#11493) Add minimal support for biblatex data annotations (JabRef#11506) Fix handling of relative-file storage and auto linking (JabRef#11492) New Crowdin updates (JabRef#11504) Add missing issue numbers CSL4LibreOffice - A [GSoC '24] (JabRef#11477) Bump src/main/resources/csl-styles from `b2be5ae` to `fd6cb3e` (JabRef#11501) Bump gittools/actions from 1.1.1 to 1.2.0 (JabRef#11500) Bump com.kohlschutter.junixsocket:junixsocket-core from 2.9.1 to 2.10.0 (JabRef#11498) Bump commons-logging:commons-logging from 1.3.2 to 1.3.3 (JabRef#11499) Bump org.jsoup:jsoup from 1.17.2 to 1.18.1 (JabRef#11497) Bump com.kohlschutter.junixsocket:junixsocket-mysql from 2.9.1 to 2.10.0 (JabRef#11496) Bump org.openrewrite.recipe:rewrite-recipe-bom from 2.14.0 to 2.15.0 (JabRef#11495) FAQ updates (JabRef#11486) Update Gradle Wrapper from 8.8 to 8.9. Fix Chocolate.bib (JabRef#11491) # Conflicts: # src/main/java/org/jabref/gui/openoffice/OOBibBase.java # src/main/java/org/jabref/gui/openoffice/OpenOfficePanel.java # src/main/java/org/jabref/gui/openoffice/StyleSelectDialogView.java # src/main/java/org/jabref/gui/openoffice/StyleSelectDialogViewModel.java # src/main/java/org/jabref/preferences/JabRefPreferences.java
FAQ updates
Additions: Guide regarding failing tests on Checkstyle, OpenRewrite, Localization, locales and ANTLR Tool.
Mandatory checks
[ ] Change inCHANGELOG.md
described in a way that is understandable for the average user (if applicable)[ ] Tests created for changes (if applicable)[ ] Manually tested changed features in running JabRef (always required)[ ] Screenshots added in PR description (for UI changes)