FAQ updates #11486
Merged
FAQ updates #11486
Conversation
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
koppor
requested changes
Jul 12, 2024
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.
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.
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.
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.
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.
Talk about "package" and "refactor"
koppor
reviewed
Jul 15, 2024
koppor
approved these changes
Jul 15, 2024
|
Proposed addition in next update: |
Siedlerchr
added a commit
to subhramit/jabref
that referenced
this pull request
Jul 19, 2024
* 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
FAQ updates
Additions: Guide regarding failing tests on Checkstyle, OpenRewrite, Localization, locales and ANTLR Tool.
Mandatory checks
[ ] Change inCHANGELOG.mddescribed 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)