diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 11163bde525..8c59721c045 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -31,9 +31,9 @@ // Install java. // See https://github.com/devcontainers/features/tree/main/src/java#options for details. "ghcr.io/devcontainers/features/java:1": { - "version": "20.0.2-tem", + "version": "21.0.1-librca", "installGradle": false, - "jdkDistro": "tem" + "jdkDistro": "librca" } } } diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 5f136688ca4..e754e4fd43e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -12,7 +12,7 @@ body: attributes: label: JabRef version options: - - "5.10 (latest release)" + - "5.11 (latest release)" - Latest development branch build (please note build date below) - Other (please describe below) description: The version as shown in the about dialog. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5ce48160d2e..16199f2abf7 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,18 @@ +### Mandatory checks -### Mandatory checks - [ ] Change in `CHANGELOG.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) diff --git a/.github/failure-csl-update.md b/.github/failure-csl-update.md deleted file mode 100644 index 0b9ab11c20f..00000000000 --- a/.github/failure-csl-update.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Error while updating citation styles -labels: code-quality, dependencies ---- -[Update of citation styles failed!](https://github.com/JabRef/jabref/actions?query=workflow%3A%22Refresh+Citation+Style+Language+Files%22) diff --git a/.github/heylogs.java b/.github/heylogs.java index 3f70faf52a0..aeeb31f8f45 100644 --- a/.github/heylogs.java +++ b/.github/heylogs.java @@ -1,4 +1,4 @@ -//DEPS com.github.nbbrd.heylogs:heylogs-cli:0.6.0 +//DEPS com.github.nbbrd.heylogs:heylogs-cli:0.7.1 public class heylogs { public static void main(String... args) throws Exception { nbbrd.heylogs.cli.HeylogsCommand.main(args); diff --git a/.github/workflows/GreetingFirstTimeCodeContribution.yml b/.github/workflows/add-greeting-to-issue.yml similarity index 95% rename from .github/workflows/GreetingFirstTimeCodeContribution.yml rename to .github/workflows/add-greeting-to-issue.yml index 9e0b3a5b2fd..5af62f225ce 100644 --- a/.github/workflows/GreetingFirstTimeCodeContribution.yml +++ b/.github/workflows/add-greeting-to-issue.yml @@ -1,4 +1,4 @@ -name: GreetingFirstTimeCodeContribution +name: Add greeting to issues for first time contributors on: issues: diff --git a/.github/workflows/add-to-projects.yml b/.github/workflows/add-to-projects.yml new file mode 100644 index 00000000000..3729f2bb062 --- /dev/null +++ b/.github/workflows/add-to-projects.yml @@ -0,0 +1,42 @@ +name: Add to Project on Label + +on: + issues: + types: [labeled] + +permissions: + issues: write + +jobs: + add-to-project: + runs-on: ubuntu-latest + + steps: + - name: "good first issue" + if: "${{ github.event.label.name == 'good first issue' }}" + env: + GH_TOKEN: ${{ github.token }} + run: | + ISSUE_URL=$(jq --raw-output .issue.html_url "$GITHUB_EVENT_PATH") + gh project item-add 5 --owner jabref --url $ISSUE_URL + - name: needs-refinement + if: github.event.label.name == 'needs-refinement' + env: + GH_TOKEN: ${{ github.token }} + run: | + ISSUE_URL=$(jq --raw-output .issue.html_url "$GITHUB_EVENT_PATH") + gh project item-add 15 --owner jabref --url $ISSUE_URL + - name: "status: freeze" + if: "${{ github.event.label.name == 'status: freeze' }}" + env: + GH_TOKEN: ${{ github.token }} + run: | + ISSUE_URL=$(jq --raw-output .issue.html_url "$GITHUB_EVENT_PATH") + gh project item-add 9 --owner jabref --url $ISSUE_URL + - name: ui + if: "${{ github.event.label.name == 'ui' }}" + env: + GH_TOKEN: ${{ github.token }} + run: | + ISSUE_URL=$(jq --raw-output .issue.html_url "$GITHUB_EVENT_PATH") + gh project item-add 8 --owner jabref --url $ISSUE_URL diff --git a/.github/workflows/automerge.yml b/.github/workflows/automerge.yml index 7fc5a3ec186..7d339a6355d 100644 --- a/.github/workflows/automerge.yml +++ b/.github/workflows/automerge.yml @@ -10,10 +10,16 @@ jobs: runs-on: ubuntu-latest # Run only if PR is inside JabRef's main repository and created by dependabot or by an update workflow if: > - (github.repository == 'JabRef/jabref') && - ((github.actor == 'dependabot[bot]') || - ((startsWith(github.event.pull_request.title, '[Bot] ') || (startsWith(github.event.pull_request.title, 'Bump '))) && - (github.event.pull_request.head.repo.full_name == 'JabRef/jabref'))) + (github.repository == 'JabRef/jabref') && + (github.event.pull_request.head.repo.full_name == 'JabRef/jabref') && + ( + (github.actor == 'dependabot[bot]') || + ( + startsWith(github.event.pull_request.title, '[Bot] ') || + startsWith(github.event.pull_request.title, 'Bump ') || + startsWith(github.event.pull_request.title, 'New Crowdin updates') + ) + ) steps: - name: Approve PR run: gh pr review --approve "$PR_URL" @@ -21,7 +27,7 @@ jobs: PR_URL: ${{github.event.pull_request.html_url}} GITHUB_TOKEN: ${{secrets.GH_TOKEN_JABREF_MACHINE_PR_APPROVE}} - name: Merge PR - run: gh pr merge --auto "$PR_URL" + run: gh pr merge --auto --squash "$PR_URL" env: PR_URL: ${{github.event.pull_request.html_url}} GITHUB_TOKEN: ${{secrets.GH_TOKEN_UPDATE_GRADLE_WRAPPER}} diff --git a/.github/workflows/deployment-arm64.yml b/.github/workflows/deployment-arm64.yml index 87338bcee4c..b5cb0cf4bc0 100644 --- a/.github/workflows/deployment-arm64.yml +++ b/.github/workflows/deployment-arm64.yml @@ -61,23 +61,9 @@ jobs: - name: Setup JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - - name: Setup JDK jabref-fix macOS - shell: bash - run: | - mkdir ${{runner.temp}}/jdk - wget -qO- https://files.jabref.org/jdks/jdk-macos-aarch64.tar.gz | tar xz -C ${{runner.temp}}/jdk - mv ${{runner.temp}}/jdk/jdk-21.jdk ${{runner.temp}}/jdk/jdk-21 - echo "JDK21=${{runner.temp}}/jdk/jdk-21" >> "$GITHUB_ENV" - ls ${{runner.temp}}/jdk - - echo "org.gradle.java.installations.paths=${{runner.temp}}/jdk/jdk-21" >> gradle.properties - echo "org.gradle.java.installations.auto-detect=false" >> gradle.properties - cat gradle.properties - - sed -i'.bak' -e "s/JavaLanguageVersion.of(20)/JavaLanguageVersion.of(21)/" build.gradle - name: Clean up keychain run: | security delete-keychain signing_temp.keychain ${{runner.temp}}/keychain/notarization.keychain || true @@ -104,9 +90,9 @@ jobs: - name: Build dmg (macOS) shell: bash run: | - ${{env.JDK21}}/Contents/Home/bin/jpackage \ + jpackage \ --module org.jabref/org.jabref.cli.Launcher \ - --module-path ${{env.JDK21}}/Contents/Home/jmods/:build/jlinkbase/jlinkjars \ + --module-path ${{env.JAVA_HOME}}/jmods/:build/jlinkbase/jlinkjars \ --add-modules org.jabref,org.jabref.merged.module \ --dest build/distribution \ --app-content buildres/mac/jabrefHost.py \ @@ -128,9 +114,9 @@ jobs: - name: Build pkg (macOS) shell: bash run: | - ${{env.JDK21}}/Contents/Home/bin/jpackage \ + jpackage \ --module org.jabref/org.jabref.cli.Launcher \ - --module-path ${{env.JDK21}}/Contents/Home/jmods/:build/jlinkbase/jlinkjars \ + --module-path ${{env.JAVA_HOME}}/jmods/:build/jlinkbase/jlinkjars \ --add-modules org.jabref,org.jabref.merged.module \ --dest build/distribution \ --app-content buildres/mac/jabrefHost.py \ diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml index fa9743d5557..c23f0ccf516 100644 --- a/.github/workflows/deployment.yml +++ b/.github/workflows/deployment.yml @@ -92,52 +92,9 @@ jobs: - name: Setup JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - - name: Setup JDK jabref-fix (Windows) - if: (matrix.os == 'windows-latest') - shell: bash - run: | - mkdir ${{runner.temp}}\jdk - curl -kLsS ${{matrix.eaJDK}} -o temp.zip && 7z x temp.zip -o"$(cygpath -u "$RUNNER_TEMP\jdk")" - echo "JDK21=${{runner.temp}}\jdk\jdk-21" >> "$GITHUB_ENV" - ls "$(cygpath -u "$RUNNER_TEMP\jdk\jdk-21")" - - echo "org.gradle.java.installations.paths=${{runner.temp}}\jdk\jdk-21" | sed "s/\\\\/\\\\\\\\/g" >> gradle.properties - echo "org.gradle.java.installations.auto-detect=false" >> gradle.properties - cat gradle.properties - - sed -i "s/JavaLanguageVersion.of(20)/JavaLanguageVersion.of(21)/" build.gradle - - name: Setup JDK jabref-fix (linux) - if: (matrix.os == 'ubuntu-latest') - shell: bash - run: | - mkdir ${{runner.temp}}/jdk - wget -qO- ${{matrix.eaJDK}} | tar xz -C ${{runner.temp}}/jdk - echo "JDK21=${{runner.temp}}/jdk/jdk-21" >> "$GITHUB_ENV" - ls ${{runner.temp}}/jdk - - echo "org.gradle.java.installations.paths=${{runner.temp}}/jdk/jdk-21" >> gradle.properties - echo "org.gradle.java.installations.auto-detect=false" >> gradle.properties - cat gradle.properties - - sed -i "s/JavaLanguageVersion.of(20)/JavaLanguageVersion.of(21)/" build.gradle - - name: Setup JDK jabref-fix (macOS) - if: (matrix.os == 'macos-latest') - shell: bash - run: | - mkdir ${{runner.temp}}/jdk - wget -qO- ${{matrix.eaJDK}} | tar xz -C ${{runner.temp}}/jdk - mv ${{runner.temp}}/jdk/jdk-21.jdk ${{runner.temp}}/jdk/jdk-21 - echo "JDK21=${{runner.temp}}/jdk/jdk-21" >> "$GITHUB_ENV" - ls ${{runner.temp}}/jdk - - echo "org.gradle.java.installations.paths=${{runner.temp}}/jdk/jdk-21" >> gradle.properties - echo "org.gradle.java.installations.auto-detect=false" >> gradle.properties - cat gradle.properties - - sed -i'.bak' -e "s/JavaLanguageVersion.of(20)/JavaLanguageVersion.of(21)/" build.gradle - name: Prepare merged jars and modules dir (macOS) if: (matrix.os == 'macos-latest') || (steps.checksecrets.outputs.secretspresent == 'NO') run: ./gradlew -i -PprojVersion="${{ steps.gitversion.outputs.AssemblySemVer }}" -PprojVersionInfo="${{ steps.gitversion.outputs.InformationalVersion }}" prepareModulesDir @@ -160,9 +117,9 @@ jobs: if: (matrix.os == 'macos-latest') && (steps.checksecrets.outputs.secretspresent == 'YES') shell: bash run: | - ${{env.JDK21}}/Contents/Home/bin/jpackage \ + jpackage \ --module org.jabref/org.jabref.cli.Launcher \ - --module-path ${{env.JDK21}}/Contents/Home/jmods/:build/jlinkbase/jlinkjars \ + --module-path ${{env.JAVA_HOME}}/jmods/:build/jlinkbase/jlinkjars \ --add-modules org.jabref,org.jabref.merged.module \ --dest build/distribution \ --app-content buildres/mac/jabrefHost.py \ @@ -185,9 +142,9 @@ jobs: if: (matrix.os == 'macos-latest') && (steps.checksecrets.outputs.secretspresent == 'YES') shell: bash run: | - ${{env.JDK21}}/Contents/Home/bin/jpackage \ + jpackage \ --module org.jabref/org.jabref.cli.Launcher \ - --module-path ${{env.JDK21}}/Contents/Home/jmods/:build/jlinkbase/jlinkjars \ + --module-path ${{env.JAVA_HOME}}/jmods/:build/jlinkbase/jlinkjars \ --add-modules org.jabref,org.jabref.merged.module \ --dest build/distribution \ --app-content buildres/mac/jabrefHost.py \ @@ -232,7 +189,7 @@ jobs: rm debian-binary control.tar.* data.tar.* mv -f jabref_${{ steps.gitversion.outputs.Major }}.${{ steps.gitversion.outputs.Minor }}_amd64_repackaged.deb jabref_${{ steps.gitversion.outputs.Major }}.${{ steps.gitversion.outputs.Minor }}_amd64.deb - name: Setup rsync (macOS) - if: (matrix.os == 'macos-latest') && (steps.checksecrets.outputs.secretspresent == 'YES') && (!startsWith(github.ref, 'refs/heads/gh-readonly-queue')) + if: ${{ (!startsWith(github.ref, 'refs/heads/gh-readonly-queue')) && (steps.checksecrets.outputs.secretspresent == 'YES') && ((matrix.os == 'macos-latest') && !((startsWith(github.ref, 'refs/tags/') || inputs.notarization == true))) }} run: brew install rsync - name: Setup rsync (Windows) if: (matrix.os == 'windows-latest') && (steps.checksecrets.outputs.secretspresent == 'YES') && (!startsWith(github.ref, 'refs/heads/gh-readonly-queue')) @@ -241,8 +198,8 @@ jobs: # We cannot use "setup-rsync", because that does not work on Windows # We do not use egor-tensin/setup-cygwin@v4, because it replaces the default shell run: choco install --no-progress rsync - - name: Setup ssh key - if: (steps.checksecrets.outputs.secretspresent == 'YES') && (!startsWith(github.ref, 'refs/heads/gh-readonly-queue')) + - name: Setup SSH key + if: ${{ (steps.checksecrets.outputs.secretspresent == 'YES') && (!startsWith(github.ref, 'refs/heads/gh-readonly-queue')) && ((matrix.os != 'macos-latest') || !((startsWith(github.ref, 'refs/tags/') || (inputs.notarization == true)))) }} run: | echo "${{ secrets.buildJabRefPrivateKey }}" > sshkey chmod 600 sshkey @@ -267,6 +224,13 @@ jobs: # tbn = to-be-notarized name: JabRef-macOS-tbn path: build/distribution + - name: Upload to GitHub workflow artifacts store + if: (steps.checksecrets.outputs.secretspresent != 'YES') + uses: actions/upload-artifact@v3 + with: + # tbn = to-be-notarized + name: JabRef-${{ matrix.os }} + path: build/distribution announce: name: Comment on pull request runs-on: ubuntu-latest @@ -285,7 +249,7 @@ jobs: env: BUILDJABREFPRIVATEKEY: ${{ secrets.buildJabRefPrivateKey }} - name: Comment PR - if: steps.checksecrets.outputs.secretspresent == 'YES' + if: (steps.checksecrets.outputs.secretspresent == 'YES') uses: thollander/actions-comment-pull-request@v2 with: message: | diff --git a/.github/workflows/refresh-journal-lists.yml b/.github/workflows/refresh-journal-lists.yml index dccbea60e00..88f43f673c1 100644 --- a/.github/workflows/refresh-journal-lists.yml +++ b/.github/workflows/refresh-journal-lists.yml @@ -30,8 +30,8 @@ jobs: - name: Set up JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - name: Check whether journal-list.mv can be generated (the "real" generation is done inside JabRef's build process) run: | diff --git a/.github/workflows/tests-fetchers.yml b/.github/workflows/tests-fetchers.yml index 4baf08e3cdd..ee155b0c243 100644 --- a/.github/workflows/tests-fetchers.yml +++ b/.github/workflows/tests-fetchers.yml @@ -48,8 +48,8 @@ jobs: - name: Set up JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - name: Run fetcher tests run: ./gradlew fetcherTest diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 2819ae4fe7d..03914a7cbb1 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -21,21 +21,24 @@ concurrency: group: tests-${{ github.head_ref }} cancel-in-progress: true +permissions: + pull-requests: write + jobs: checkstyle: - name: Code style check + name: Checkstyle runs-on: ubuntu-latest steps: - name: Checkout source uses: actions/checkout@v4 with: - submodules: 'false' + submodules: 'true' show-progress: 'false' - name: Set up JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - name: Run checkstyle reporter uses: nikitasavinov/checkstyle-action@master @@ -52,6 +55,7 @@ jobs: with: message: > Your code currently does not meet JabRef's code guidelines. + We use [Checkstyle](https://checkstyle.sourceforge.io/) to identify issues. The tool reviewdog already placed comments on GitHub to indicate the places. See the tab "Files" in you PR. Please carefully follow [the setup guide for the codestyle](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/intellij-13-code-style.html). Afterwards, please run checkstyle locally and fix the issues. @@ -59,17 +63,71 @@ jobs: More information on code quality in JabRef is available at . comment_tag: checkstyle - reactions: eyes + openrewrite: + name: OpenRewrite + runs-on: ubuntu-latest + steps: + - name: Checkout source + uses: actions/checkout@v4 + with: + submodules: 'true' + show-progress: 'false' + - name: Set up JDK + uses: actions/setup-java@v3 + with: + java-version: 21.0.1 + distribution: 'liberica' + cache: 'gradle' - name: Run OpenRewrite run: | ./gradlew rewriteDryRun + - name: Add comment on pull request + if: ${{ failure() }} + uses: thollander/actions-comment-pull-request@v2 + with: + message: > + Your code currently does not meet JabRef's code guidelines. + We use [OpenRewrite](https://docs.openrewrite.org/) to ensure "modern" Java coding practices. + The issues found can be **automatically fixed**. + Please execute the gradle task *`rewriteRun`*, check the results, commit, and push. + + + You can check the detailed error output at the tab "Checks", section "Tests" (on the left), subsection "OpenRewrite". + comment_tag: openrewrite + modernizer: + name: Modernizer + runs-on: ubuntu-latest + steps: + - name: Checkout source + uses: actions/checkout@v4 + with: + submodules: 'true' + show-progress: 'false' + - name: Set up JDK + uses: actions/setup-java@v3 + with: + java-version: 21.0.1 + distribution: 'liberica' + cache: 'gradle' - name: Run modernizer run: | # enable failing of this task if modernizer complains sed -i "s/failOnViolations = false/failOnViolations = true/" build.gradle ./gradlew modernizer - markdown-checks: - name: Markdown style check + - name: Add comment on pull request + if: ${{ failure() }} + uses: thollander/actions-comment-pull-request@v2 + with: + message: > + Your code currently does not meet JabRef's code guidelines. + We use [Gradle Modernizer Plugin](https://github.com/andygoossens/gradle-modernizer-plugin#gradle-modernizer-plugin) to ensure "modern" Java coding practices. + Please fix the detected errors, commit, and push. + + + You can check the detailed error output at the tab "Checks", section "Tests" (on the left), subsection "Modernizer". + comment_tag: modernizer + markdown: + name: Markdown runs-on: ubuntu-latest steps: - name: Checkout source @@ -77,20 +135,67 @@ jobs: with: submodules: 'false' show-progress: 'false' - - name: Run markdown-lint - uses: avto-dev/markdown-lint@v1 + - name: markdownlint-cli2-action + uses: DavidAnson/markdownlint-cli2-action@v13 with: - args: CHANGELOG.md CONTRIBUTING.md README.md - config: '.markdownlint.yml' + globs: | + *.md + docs/**/*.md + - name: Add comment on pull request + if: ${{ failure() }} + uses: thollander/actions-comment-pull-request@v2 + with: + message: > + You modified Markdown (*.md) files. + To ensure consistent styling, we have [markdown-lint](https://github.com/DavidAnson/markdownlint) in place. + [Markdown lint's rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#rules) help to keep our Markdown files consistent within this repository and consistent with the Markdown files outside here. + + You can check the detailed error output at the tab "Checks", section "Tests" (on the left), subsection "Markdown". + comment_tag: markdown + changelog-non-frozen: + name: CHANGELOG.md + runs-on: ubuntu-latest + steps: + - name: Checkout source + uses: actions/checkout@v4 + with: + submodules: 'false' + show-progress: 'false' + fetch-depth: 0 - name: Lint CHANGELOG.md run: | - set -e + # Install jbang curl -Ls https://sh.jbang.dev | bash -s - app setup - source ~/.zshrc - jbang .github/heylogs.java check CHANGELOG.md > heylogs.txt + export PATH=$PATH:$HOME/.jbang/bin + + # ensure that refs are available + BRANCH=`git rev-parse HEAD` + git checkout main + + # run heylogs verification + jbang --repos jitpack,central -m nbbrd.heylogs.cli.HeylogsCommand com.github.koppor.heylogs:heylogs-cli:jitpack-SNAPSHOT check CHANGELOG.md --gitdiff main...$BRANCH > heylogs.txt || true + + # improve output + sed -i 's/consistent-separator/consistent-separator (ignored)/' heylogs.txt + sed -i 's/all-h2-contain-a-version/all-h2-contain-a-version (ignored)/' heylogs.txt + cat heylogs.txt - # We have 7 "valid" issues in CHANGELOG.md - grep -q "7 problems" heylogs.txt || exit 1 + + # exit 1 in case of error + # We have 2 "valid" issues in CHANGELOG.md + grep -q "2 problems" heylogs.txt || exit 1 + - name: Add comment on pull request + if: ${{ failure() }} + uses: thollander/actions-comment-pull-request@v2 + with: + message: > + While the PR was in progress, JabRef released a new version. + You have to merge `upstream/main` and move your entry in `CHANGELOG.md` to section `## [Unreleased]`. + + + It might also be that another CHANGELOG.md issue arose. + You can check the detailed error output at the tab "Checks", section "Tests" (on the left), subsection "CHANGELOG.md". + comment_tag: changelog tests: name: Unit tests runs-on: ubuntu-latest @@ -103,8 +208,8 @@ jobs: - name: Set up JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - name: Run tests run: xvfb-run --auto-servernum ./gradlew check -x checkstyleJmh -x checkstyleMain -x checkstyleTest -x modernizer @@ -138,8 +243,8 @@ jobs: - name: Set up JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - name: Run tests on PostgreSQL run: ./gradlew databaseTest --rerun-tasks @@ -175,8 +280,8 @@ jobs: - name: Set up JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - name: Run GUI tests run: xvfb-run --auto-servernum ./gradlew guiTest @@ -216,8 +321,8 @@ jobs: - name: Set up JDK uses: actions/setup-java@v3 with: - java-version: 20 - distribution: 'temurin' + java-version: 21.0.1 + distribution: 'liberica' cache: 'gradle' - name: Update test coverage metrics if: steps.checksecrets.outputs.secretspresent == 'YES' diff --git a/.gitignore b/.gitignore index 1d3864a220b..72603d9dc08 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ src/main/gen/ src/main/generated/ src-gen/ +# generated by https://plugins.jetbrains.com/plugin/15991-plantuml-diagram-generator +*.puml + structure101-settings.java.hsw # private data @@ -59,8 +62,8 @@ jabref.xml ## !! IN CASE YOU UPDATE, PLEASE KEEP THE LINES AT THE END OF THE FILE !! -# Created by https://www.gitignore.io/api/gradle,java,jabref,intellij,eclipse,netbeans,windows,linux,macos,node,snapcraft -# Edit at https://www.gitignore.io/?templates=gradle,java,jabref,intellij,eclipse,netbeans,windows,linux,macos,node,snapcraft +# Created by https://www.toptal.com/developers/gitignore/api/gradle,java,jabref,jetbrains,eclipse,netbeans,windows,linux,macos,node,snapcraft +# Edit at https://www.toptal.com/developers/gitignore?templates=gradle,java,jabref,jetbrains,eclipse,netbeans,windows,linux,macos,node,snapcraft ### Eclipse ### .metadata @@ -113,26 +116,53 @@ local.properties # Annotation Processing .apt_generated/ +.apt_generated_test/ # Scala IDE specific (Scala & Java development for Eclipse) .cache-main .scala_dependencies .worksheet +# Uncomment this line if you wish to ignore the project description file. +# Typically, this file would be tracked if it contains build/dependency configurations: +#.project + ### Eclipse Patch ### -# Eclipse Core -.project +# Spring Boot Tooling +.sts4-cache/ -# JDT-specific (Eclipse Java Development Tools) -.classpath +### JabRef ### +# JabRef - https://www.jabref.org/ +*.sav -# Annotation Processing -.apt_generated +### Java ### +# Compiled class file +*.class -.sts4-cache/ +# Log file +*.log + +# BlueJ files +*.ctxt + +# Mobile Tools for Java (J2ME) +.mtj.tmp/ + +# Package Files # +*.jar +*.war +*.nar +*.ear +*.zip +*.tar.gz +*.rar -### Intellij ### -# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm +# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml +hs_err_pid* +replay_pid* + +### JetBrains ### +# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 # User-specific stuff @@ -142,6 +172,9 @@ local.properties .idea/**/dictionaries .idea/**/shelf +# AWS User-specific +.idea/**/aws.xml + # Generated files .idea/**/contentModel.xml @@ -162,6 +195,9 @@ local.properties # When using Gradle or Maven with auto-import, you should exclude module files, # since they will be recreated, and may cause churn. Uncomment if using # auto-import. +# .idea/artifacts +# .idea/compiler.xml +# .idea/jarRepositories.xml # .idea/modules.xml # .idea/*.iml # .idea/modules @@ -189,6 +225,9 @@ atlassian-ide-plugin.xml # Cursive Clojure plugin .idea/replstate.xml +# SonarLint plugin +.idea/sonarlint/ + # Crashlytics plugin (for Android Studio and IntelliJ) com_crashlytics_export_strings.xml crashlytics.properties @@ -201,7 +240,7 @@ fabric.properties # Android studio 3.1+ serialized cache file .idea/caches/build_file_checksums.ser -### Intellij Patch ### +### JetBrains Patch ### # Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721 # *.iml @@ -210,43 +249,30 @@ fabric.properties # *.ipr # Sonarlint plugin +# https://plugins.jetbrains.com/plugin/7973-sonarlint .idea/**/sonarlint/ # SonarQube Plugin +# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin .idea/**/sonarIssues.xml # Markdown Navigator plugin +# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced .idea/**/markdown-navigator.xml +.idea/**/markdown-navigator-enh.xml .idea/**/markdown-navigator/ -### JabRef ### -# JabRef - https://www.jabref.org/ -*.sav - -### Java ### -# Compiled class file -*.class - -# Log file -*.log +# Cache file creation bug +# See https://youtrack.jetbrains.com/issue/JBR-2257 +.idea/$CACHE_FILE$ -# BlueJ files -*.ctxt +# CodeStream plugin +# https://plugins.jetbrains.com/plugin/12206-codestream +.idea/codestream.xml -# Mobile Tools for Java (J2ME) -.mtj.tmp/ - -# Package Files # -*.jar -*.war -*.nar -*.ear -*.zip -*.tar.gz -*.rar - -# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml -hs_err_pid* +# Azure Toolkit for IntelliJ plugin +# https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij +.idea/**/azureSettings.xml ### Linux ### *~ @@ -272,6 +298,7 @@ hs_err_pid* # Icon must end with two \r Icon + # Thumbnails ._* @@ -291,6 +318,10 @@ Network Trash Folder Temporary Items .apdisk +### macOS Patch ### +# iCloud generated files +*.icloud + ### NetBeans ### **/nbproject/private/ **/nbproject/Makefile-*.mk @@ -308,6 +339,7 @@ npm-debug.log* yarn-debug.log* yarn-error.log* lerna-debug.log* +.pnpm-debug.log* # Diagnostic reports (https://nodejs.org/api/report.html) report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json @@ -344,8 +376,8 @@ build/Release node_modules/ jspm_packages/ -# TypeScript v1 declaration files -typings/ +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ # TypeScript cache *.tsbuildinfo @@ -356,6 +388,15 @@ typings/ # Optional eslint cache .eslintcache +# Optional stylelint cache +.stylelintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + # Optional REPL history .node_repl_history @@ -365,33 +406,40 @@ typings/ # Yarn Integrity file .yarn-integrity -# dotenv environment variables file +# dotenv environment variable files .env -.env.test +.env.development.local +.env.test.local +.env.production.local +.env.local # parcel-bundler cache (https://parceljs.org/) .cache +.parcel-cache -# next.js build output +# Next.js build output .next +out -# nuxt.js build output +# Nuxt.js build / generate output .nuxt +dist -# rollup.js default build output - -# Uncomment the public line if your project uses Gatsby +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js # https://nextjs.org/blog/next-9-1#public-directory-support -# https://create-react-app.dev/docs/using-the-public-folder/#docsNav # public -# Storybook build outputs -.out -.storybook-out - # vuepress build output .vuepress/dist +# vuepress v2.x temp and cache directory +.temp + +# Docusaurus cache and generated files +.docusaurus + # Serverless directories .serverless/ @@ -401,8 +449,27 @@ typings/ # DynamoDB Local files .dynamodb/ -# Temporary folders -temp/ +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + +### Node Patch ### +# Serverless Webpack directories +.webpack/ + +# Optional stylelint cache + +# SvelteKit build / generate output +.svelte-kit ### Snapcraft ### /parts/ @@ -445,6 +512,8 @@ $RECYCLE.BIN/ ### Gradle ### .gradle +**/build/ +!src/**/build/ # Ignore Gradle GUI config gradle-app.setting @@ -452,16 +521,24 @@ gradle-app.setting # Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored) !gradle-wrapper.jar +# Avoid ignore Gradle wrappper properties +!gradle-wrapper.properties + # Cache of project .gradletasknamecache -# # Work around https://youtrack.jetbrains.com/issue/IDEA-116898 -# gradle/wrapper/gradle-wrapper.properties +# Eclipse Gradle plugin generated files +# Eclipse Core +.project +# JDT-specific (Eclipse Java Development Tools) +.classpath ### Gradle Patch ### -**/build/ +# Java heap dump +*.hprof + +# End of https://www.toptal.com/developers/gitignore/api/gradle,java,jabref,jetbrains,eclipse,netbeans,windows,linux,macos,node,snapcraft -# End of https://www.gitignore.io/api/gradle,java,jabref,intellij,eclipse,netbeans,windows,linux,macos,node,snapcraft ## !! KEEP THESE LINES !! diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile index 007108a0f49..0e80edc3ec8 100644 --- a/.gitpod.Dockerfile +++ b/.gitpod.Dockerfile @@ -5,4 +5,4 @@ FROM gitpod/workspace-full # All available versions can be listed using sdk ls java # More information about SDKMAN available at https://github.com/sdkman/sdkman-cli#sdkman-cli RUN bash -c ". /home/gitpod/.sdkman/bin/sdkman-init.sh \ - && sdk install java 18.0.1.1-open" + && sdk install java 21-open" diff --git a/.vscode/ltex.dictionary.en-US.txt b/.vscode/ltex.dictionary.en-US.txt index e674b7db451..1345f479d73 100644 --- a/.vscode/ltex.dictionary.en-US.txt +++ b/.vscode/ltex.dictionary.en-US.txt @@ -1,3 +1,5 @@ +Checkstyle +CouchDB JabDrive JabRef -CouchDB +OpenRewrite diff --git a/CHANGELOG.md b/CHANGELOG.md index e441dbc7029..23985fb68e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,27 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv ### Added +- We added a dropdown menu to let users change the reference library during AUX file import. [#10472](https://github.com/JabRef/jabref/issues/10472) +- We added a button to let users reset the cite command to the default value. [#10569](https://github.com/JabRef/jabref/issues/10569) + +### Changed + +- We moved the location of the 'Open only one instance of JabRef' preference option from "Network" to "General". [#9306](https://github.com/JabRef/jabref/issues/9306) +- The two previews in the change resolver dialog now have their scrollbars synchronized. [#9576](https://github.com/JabRef/jabref/issues/9576). +- We changed the setting of the keyword separator to accept a single character only. [#177](https://github.com/koppor/jabref/issues/177) + +### Fixed + +- We fixed an issue where the added protected term has unwanted leading and trailing whitespaces, where the formatted text has unwanted empty brackets and where the word at the cursor in the textbox can be added to the list. [#10415](https://github.com/JabRef/jabref/issues/10415). +- We fixed an issue where in the merge dialog the file field of entries was not correctly merged when the first and second entry both contained values inside the file field. [#10572](https://github.com/JabRef/jabref/issues/10572) + +### Removed + +## [5.11] – 2023-10-22 + +### Added + +- We added the ability to sort subgroups in Z-A order, as well as by ascending and descending number of subgroups. [#10249](https://github.com/JabRef/jabref/issues/10249) - We added the possibility to find (and add) papers that cite or are cited by a given paper. [#6187](https://github.com/JabRef/jabref/issues/6187) - We added an error-specific message for when a download from a URL fails. [#9826](https://github.com/JabRef/jabref/issues/9826) - We added support for customizing the citation command (e.g., `[@key1,@key2]`) when [pushing to external applications](https://docs.jabref.org/cite/pushtoapplications). [#10133](https://github.com/JabRef/jabref/issues/10133) @@ -19,8 +40,10 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We added a link "Get more themes..." in the preferences to that points to [themes.jabref.org](https://themes.jabref.org) allowing the user to download new themes. [#10243](https://github.com/JabRef/jabref/issues/10243) - We added a fetcher for [LOBID](https://lobid.org/resources/api) resources. [koppor#386](https://github.com/koppor/jabref/issues/386) - When in `biblatex` mode, the [integrity check](https://docs.jabref.org/finding-sorting-and-cleaning-entries/checkintegrity) for journal titles now also checks the field `journal`. +- We added support for exporting to Hayagriva YAML format. [#10382](https://github.com/JabRef/jabref/issues/10382) - We added support for pushing citations to [TeXShop](https://pages.uoregon.edu/koch/texshop/) on macOS [forum#2699](https://discourse.jabref.org/t/push-to-texshop-mac/2699). - We added ability to jump to an entry in the command line using `-j CITATIONKEY [BIBTEXFILES]`. [koppor#540](https://github.com/koppor/jabref/issues/540) +- We added the 'Bachelor's thesis' type for Biblatex's 'Thesis' EntryType [#10029](https://github.com/JabRef/jabref/issues/10029). ### Changed @@ -31,6 +54,8 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We modified the DOI cleanup to infer the DOI from an ArXiV ID if it's present. [#10426](https://github.com/JabRef/jabref/issues/10426) - The ISI importer uses the field `comment` for notes (instead of `review). [#10478](https://github.com/JabRef/jabref/pull/10478) - If no existing document is selected for exporting "Embedded BibTeX pdf" JabRef will now create a new PDF file with a sample text and the metadata. [#10101](https://github.com/JabRef/jabref/issues/10101) +- Translated titles format no longer raise a warning. [#10459](https://github.com/JabRef/jabref/issues/10459) +- We re-added the empty grey containers in the groups panel to keep an indicator for the current selected group, if displaying of group item count is turned off [#9972](https://github.com/JabRef/jabref/issues/9972) ### Fixed @@ -49,11 +74,13 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We fixed an issue where the "Enabled" column in the "Protected terms files" tab in the preferences could not be resized [#10285](https://github.com/JabRef/jabref/issues/10285) - We fixed an issue where after creation of a new library, the new library was not focused. [koppor#592](https://github.com/koppor/jabref/issues/592) - We fixed an issue where double clicking on an url in the file field would trigger an exception instead of opening the browser [#10480](https://github.com/JabRef/jabref/pull/10480) +- We fixed an issue where scrolling was impossible on dragging a citation on the groups panel. [#9754](https://github.com/JabRef/jabref/issues/9754) - We fixed an issue where exporting "Embedded BibTeX pdf" without selecting an existing document would produce an exception. [#10101](https://github.com/JabRef/jabref/issues/10101) +- We fixed an issue where there was a failure to access the url link for "eprint" for the ArXiv entry.[#10474](https://github.com/JabRef/jabref/issues/10474) +- We fixed an issue where it was not possible to connect to a shared database once a group with entries was added or other metadata modified [#10336](https://github.com/JabRef/jabref/issues/10336) +- We fixed an issue where middle-button paste in X not always worked [#7905](https://github.com/JabRef/jabref/issues/7905) -### Removed - -## [5.10] - 2023-09-02 +## [5.10] – 2023-09-02 ### Added @@ -193,7 +220,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We removed the 'File' tab in the preferences and moved its contents to the 'Export' tab. [#9839](https://github.com/JabRef/jabref/pull/9839) - We removed the "[Collection of Computer Science Bibliographies](https://en.wikipedia.org/wiki/Collection_of_Computer_Science_Bibliographies)" fetcher the websits is no longer available. [#6638](https://github.com/JabRef/jabref/issues/6638) -## [5.9] - 2023-01-06 +## [5.9] – 2023-01-06 ### Added @@ -226,7 +253,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We fixed an issue with open office csv file formatting where commas in the abstract field where not escaped. [#9087](https://github.com/JabRef/jabref/issues/9087) - We fixed an issue with deleting groups where subgroups different from the selected group were deleted. [#9281](https://github.com/JabRef/jabref/issues/9281) -## [5.8] - 2022-12-18 +## [5.8] – 2022-12-18 ### Added @@ -319,7 +346,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We removed "last-search-date" from the systematic literature review feature, because the last-search-date can be deducted from the git logs. [#9116](https://github.com/JabRef/jabref/pull/9116) - We removed the [CiteseerX](https://docs.jabref.org/collect/import-using-online-bibliographic-database#citeseerx) fetcher, because the API used by JabRef is sundowned. [#9466](https://github.com/JabRef/jabref/pull/9466) -## [5.7] - 2022-08-05 +## [5.7] – 2022-08-05 ### Added @@ -385,7 +412,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We removed the social media buttons for our Twitter and Facebook pages. [#8774](https://github.com/JabRef/jabref/issues/8774) -## [5.6] - 2022-04-25 +## [5.6] – 2022-04-25 ### Added @@ -445,7 +472,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We removed the option to copy CSL Citation styles data as `XSL_FO`, `ASCIIDOC`, and `RTF` as these have not been working since a long time and are no longer supported in the external library used for processing the styles. [#7378](https://github.com/JabRef/jabref/issues/7378) - We removed the option to configure the default encoding. The default encoding is now hard-coded to the modern UTF-8 encoding. -## [5.5] - 2022-01-17 +## [5.5] – 2022-01-17 ### Changed @@ -471,7 +498,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv - We fixed an issue when writing a non-UTF-8 encoded file: The header is written again. [#8417](https://github.com/JabRef/jabref/issues/8417) - We fixed an issue where folder creation during systemic literature review failed due to an illegal fetcher name. [#8552](https://github.com/JabRef/jabref/pull/8552) -## [5.4] - 2021-12-20 +## [5.4] – 2021-12-20 ### Added @@ -1155,7 +1182,8 @@ The changelog of JabRef 4.x is available at the [v4.3.1 tag](https://github.com/ The changelog of JabRef 3.x is available at the [v3.8.2 tag](https://github.com/JabRef/jabref/blob/v3.8.2/CHANGELOG.md). The changelog of JabRef 2.11 and all previous versions is available as [text file in the v2.11.1 tag](https://github.com/JabRef/jabref/blob/v2.11.1/CHANGELOG). -[Unreleased]: https://github.com/JabRef/jabref/compare/v5.10...HEAD +[Unreleased]: https://github.com/JabRef/jabref/compare/v5.11...HEAD +[5.11]: https://github.com/JabRef/jabref/compare/v5.10...v5.11 [5.10]: https://github.com/JabRef/jabref/compare/v5.9...v5.10 [5.9]: https://github.com/JabRef/jabref/compare/v5.8...v5.9 [5.8]: https://github.com/JabRef/jabref/compare/v5.7...v5.8 @@ -1169,4 +1197,4 @@ The changelog of JabRef 2.11 and all previous versions is available as [text fil [5.0]: https://github.com/JabRef/jabref/compare/v5.0-beta...v5.0 [5.0-beta]: https://github.com/JabRef/jabref/compare/v5.0-alpha...v5.0-beta [5.0-alpha]: https://github.com/JabRef/jabref/compare/v4.3...v5.0-alpha - + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a9eb0afe0d..4aebe4a5b6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,13 +3,13 @@ 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. -Support on **code contribution** is available at . +Support on **code contribution** is available at . General overview about contributing for programmers and non-programmers is available at . ## Pull Request Process -1. Understand the basics listed at . +1. Understand the basics listed at . 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. They 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 diff --git a/LICENSE.md b/LICENSE similarity index 91% rename from LICENSE.md rename to LICENSE index 410b297cab4..37471bcae7e 100644 --- a/LICENSE.md +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright © 2003-2023 [JabRef Authors](https://github.com/JabRef/jabref/blob/master/AUTHORS) +Copyright © 2003-2023 JabRef Authors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/PRIVACY.md b/PRIVACY.md index f5552fed91b..d7a1ca68b48 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -111,10 +111,12 @@ This privacy policy is in effect as of the day mentioned as "last updated" above ## Contact -If you get in touch with us, we may aks you to provide us with certain personal information (e.g. name and email address) to stay in contact with you. +If you get in touch with us, we may ask you to provide us with certain personal information (e.g. name and email address) to stay in contact with you. For any questions or concerns regarding the privacy policy, please send us an email to or write to JabRef e.V. Josef-Lanner-Str. 9 71069 Sindelfingen Germany + + diff --git a/README.md b/README.md index f8e65405ad6..f3b478a77e0 100644 --- a/README.md +++ b/README.md @@ -18,13 +18,13 @@ It supports you in every step of your research work. - Easily retrieve and link full-text articles - Fetch complete bibliographic information based on ISBN, DOI, PubMed-ID and arXiv-ID - Extract metadata from PDFs -- Import new references directly from the browser with one click using the [official browser extension](https://github.com/JabRef/JabRef-Browser-Extension) for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jabref/?src=external-github), [Chrome](https://chrome.google.com/webstore/detail/jabref-browser-extension/bifehkofibaamoeaopjglfkddgkijdlh), [Edge](https://microsoftedge.microsoft.com/addons/detail/pgkajmkfgbehiomipedjhoddkejohfna) and [Vivaldi](https://chrome.google.com/webstore/detail/jabref-browser-extension/bifehkofibaamoeaopjglfkddgkijdlh) +- Import new references directly from the browser with one click using the [official browser extension](https://github.com/JabRef/JabRef-Browser-Extension) for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jabref/?src=external-github), [Chrome](https://chrome.google.com/webstore/detail/jabref-browser-extension/bifehkofibaamoeaopjglfkddgkijdlh), [Edge](https://microsoftedge.microsoft.com/addons/detail/pgkajmkfgbehiomipedjhoddkejohfna), and [Vivaldi](https://chrome.google.com/webstore/detail/jabref-browser-extension/bifehkofibaamoeaopjglfkddgkijdlh) ### Organize -- Group your research into hierarchical collections and organize research items based on keywords/tags, search terms or your manual assignments +- Group your research into hierarchical collections and organize research items based on keywords/tags, search terms, or your manual assignments - Advanced search and filter features -- Complete and fix bibliographic data by comparing with curated online catalogs such as Google Scholar, Springer or MathSciNet +- Complete and fix bibliographic data by comparing with curated online catalogs such as Google Scholar, Springer, or MathSciNet - Customizable citation key generator - Customize and add new metadata fields or reference types - Find and merge duplicates @@ -99,6 +99,5 @@ For IntelliJ IDEA, just import the project via a Gradle Import by pointing at th ## Sponsoring -JabRef development is powered by YourKit Java Profiler [![YourKit Java Profiler](https://www.yourkit.com/images/yk_logo.svg)](https://www.yourkit.com/java/profiler/) - -[JabRef]: https://www.jabref.org +JabRef development is powered by YourKit Java Profiler +[![YourKit Java Profiler](https://www.yourkit.com/images/yk_logo.svg)](https://www.yourkit.com/java/profiler/) diff --git a/build.gradle b/build.gradle index 8705f41aaf0..4646a32c645 100644 --- a/build.gradle +++ b/build.gradle @@ -5,19 +5,19 @@ import org.jabref.build.xjc.XjcTask plugins { id 'application' - id 'com.github.andygoossens.modernizer' version '1.8.0' + id 'com.github.andygoossens.modernizer' version '1.9.0' - id 'me.champeau.jmh' version '0.7.1' + id 'me.champeau.jmh' version '0.7.2' id 'org.javamodularity.moduleplugin' version '1.8.12' id 'org.openjfx.javafxplugin' version '0.1.0' - id 'org.beryx.jlink' version '3.0.0' + id 'org.beryx.jlink' version '3.0.1' // nicer test outputs during running and completion // Homepage: https://github.com/radarsh/gradle-test-logger-plugin - id 'com.adarshr.test-logger' version '3.2.0' + id 'com.adarshr.test-logger' version '4.0.0' id 'jacoco' @@ -27,7 +27,7 @@ plugins { id 'idea' - id 'org.openrewrite.rewrite' version '6.3.18' + id 'org.openrewrite.rewrite' version '6.4.0' } // Enable following for debugging @@ -48,7 +48,9 @@ java { modularity.inferModulePath.set(false) toolchain { - // If this is updated, also update .devcontainer/devcontainer.json#L34 + // If this is updated, also update + // - .devcontainer/devcontainer.json#L34 and + // - .gitpod.Dockerfile languageVersion = JavaLanguageVersion.of(21) } } @@ -128,7 +130,7 @@ dependencies { // required for reading write-protected PDFs - see https://github.com/JabRef/jabref/pull/942#issuecomment-209252635 implementation 'org.bouncycastle:bcprov-jdk18on:1.76' - implementation 'commons-cli:commons-cli:1.5.0' + implementation 'commons-cli:commons-cli:1.6.0' implementation 'org.libreoffice:unoloader:7.6.1' implementation 'org.libreoffice:libreoffice:7.6.1' @@ -142,8 +144,10 @@ dependencies { implementation group: 'org.eclipse.jgit', name: 'org.eclipse.jgit', version: '6.7.0.202309050840-r' - implementation group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-yaml', version: '2.15.2' - implementation group: 'com.fasterxml.jackson.datatype', name: 'jackson-datatype-jsr310', version: '2.15.2' + implementation group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-yaml', version: '2.15.3' + implementation group: 'com.fasterxml.jackson.datatype', name: 'jackson-datatype-jsr310', version: '2.15.3' + + implementation 'com.fasterxml:aalto-xml:1.3.2' implementation group: 'org.mariadb.jdbc', name: 'mariadb-java-client', version: '2.7.9' @@ -154,7 +158,7 @@ dependencies { exclude module: 'oraclepki' } - implementation ('com.google.guava:guava:32.1.2-jre') { + implementation ('com.google.guava:guava:32.1.3-jre') { // TODO: Remove this as soon as https://github.com/google/guava/issues/2960 is fixed exclude module: "jsr305" } @@ -170,7 +174,7 @@ dependencies { implementation('com.tobiasdiez:easybind:2.2.1-SNAPSHOT') implementation 'org.fxmisc.flowless:flowless:0.7.1' implementation 'org.fxmisc.richtext:richtextfx:0.11.1' - implementation (group: 'com.dlsc.gemsfx', name: 'gemsfx', version: '1.82.0') { + implementation (group: 'com.dlsc.gemsfx', name: 'gemsfx', version: '1.84.0') { exclude module: 'javax.inject' // Split package, use only jakarta.inject exclude group: 'org.apache.logging.log4j' } @@ -187,6 +191,8 @@ dependencies { // route all requests to java.util.logging to SLF4J (which in turn routes to tinylog) implementation 'org.slf4j:jul-to-slf4j:2.0.9' + // route all requests to log4j to SLF4J + implementation 'org.apache.logging.log4j:log4j-to-slf4j:2.21.1' implementation('de.undercouch:citeproc-java:3.0.0-beta.2') { exclude group: 'org.antlr' @@ -205,11 +211,6 @@ dependencies { exclude group: "org.apache.xmlgraphics" } - implementation group: 'com.microsoft.azure', name: 'applicationinsights-core', version: '2.4.1' - implementation (group: 'com.microsoft.azure', name: 'applicationinsights-logging-log4j2', version: '2.4.1') { - exclude module: "log4j-core" - } - implementation 'com.vladsch.flexmark:flexmark:0.64.8' implementation group: 'net.harawata', name: 'appdirs', version: '1.2.2' @@ -222,7 +223,7 @@ dependencies { implementation 'org.glassfish.jersey.core:jersey-server:3.1.3' // injection framework implementation 'org.glassfish.jersey.inject:jersey-hk2:3.1.3' - implementation 'org.glassfish.hk2:hk2-api:3.0.4' + implementation 'org.glassfish.hk2:hk2-api:3.0.5' // testImplementation 'org.glassfish.hk2:hk2-testing:3.0.4' // implementation 'org.glassfish.hk2:hk2-testing-jersey:3.0.4' // testImplementation 'org.glassfish.hk2:hk2-junitrunner:3.0.4' @@ -233,7 +234,7 @@ dependencies { // Allow objects "magically" to be mapped to JSON using GSON // implementation 'org.glassfish.jersey.media:jersey-media-json-gson:3.1.1' - testImplementation 'io.github.classgraph:classgraph:4.8.162' + testImplementation 'io.github.classgraph:classgraph:4.8.163' testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0' testImplementation 'org.junit.platform:junit-platform-launcher:1.10.0' @@ -251,7 +252,7 @@ dependencies { xjc group: 'org.glassfish.jaxb', name: 'jaxb-xjc', version: '3.0.2' xjc group: 'org.glassfish.jaxb', name: 'jaxb-runtime', version: '3.0.2' - rewrite(platform("org.openrewrite.recipe:rewrite-recipe-bom:2.3.1")) + rewrite(platform("org.openrewrite.recipe:rewrite-recipe-bom:latest.integration")) rewrite("org.openrewrite.recipe:rewrite-static-analysis") rewrite("org.openrewrite.recipe:rewrite-logging-frameworks") rewrite("org.openrewrite.recipe:rewrite-testing-frameworks") diff --git a/docs/README.md b/docs/README.md index fad376b6982..18c6f411667 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,7 @@ Installing the latest version of ruby followed by `gem install bundler` should b Afterwards, run -```terminal +```shell bundle install jekyll serve --livereload ``` @@ -18,7 +18,7 @@ and go to in your browser. On **Windows**, using a dockerized environment is recommended: -```terminal +```shell docker build . -t jrjekyll docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\jabref\docs":/srv/jekyll jrjekyll jekyll serve -H 0.0.0.0 -t ``` @@ -27,3 +27,13 @@ docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\jabref\docs":/srv * In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun. * The current `Dockerfile` is based on . The [Jekyll Docker image](https://github.com/envygeeks/jekyll-docker#jekyll-docker) did not work end of 2022 (because Ruby was too new). + +## Execute linting action + +You can execute the linting action as if it was executed by GitHub by executing following command. + +```shell +act --rm --platform ubuntu-latest=fwilhe2/act-runner:latest -W .github/workflows/tests.yml -j "markdown" +``` + +That command uses [act](https://github.com/nektos/act), which brings GitHub actions execution to the developer machine. diff --git a/docs/code-howtos/code-quality.md b/docs/code-howtos/code-quality.md index 755b0e1d500..b78df2a5775 100644 --- a/docs/code-howtos/code-quality.md +++ b/docs/code-howtos/code-quality.md @@ -3,12 +3,26 @@ parent: Code Howtos --- # Code Quality +## Code style checkers + +JabRef has three code style checkers in place: + +* [Checkstyle](https://checkstyle.sourceforge.io/) for basic checks, such as wrong import order. +* [Gradle Modernizer Plugin](https://github.com/andygoossens/gradle-modernizer-plugin#gradle-modernizer-plugin) for Java library usage checks. It ensures that "modern" Java concepts are used (e.g., [one should use `Deque` instead of `Stack`](https://stackoverflow.com/a/73021741/873282)). +* [OpenRewrite](https://docs.openrewrite.org/) for advanced rules. OpenRewrite can also automatically fix issues. JabRef's CI toolchain does NOT automatically rewrite the source code, but checks whether OpenRewrite would rewrite something. As developer, one can execute `./gradlew rewriteRun` to fix the issues. + +In case a check fails, [the CI](https://github.com/JabRef/jabref/blob/main/.github/workflows/tests.yml#L24C6-L24C6) automatically adds a comment on the pull request. + +## Monitoring + We monitor the general source code quality at three places: * [codacy](https://www.codacy.com) is a hosted service to monitor code quality. It thereby combines the results of available open source code quality checkers such as [Checkstyle](https://checkstyle.sourceforge.io) or [PMD](https://pmd.github.io). The code quality analysis for JabRef is available at [https://app.codacy.com/gh/JabRef/jabref/dashboard](https://app.codacy.com/gh/JabRef/jabref/dashboard), especially the [list of open issues](https://app.codacy.com/gh/JabRef/jabref/issues/index). In case a rule feels wrong, it is most likely a PMD rule. The JabRef team can change the configuration at [https://app.codacy.com/p/306789/patterns/list?engine=9ed24812-b6ee-4a58-9004-0ed183c45b8f](https://app.codacy.com/p/306789/patterns/list?engine=9ed24812-b6ee-4a58-9004-0ed183c45b8f). * [codecov](https://codecov.io) is a solution to check code coverage of test cases. The code coverage metrics for JabRef are available at [https://codecov.io/github/JabRef/jabref](https://codecov.io/github/JabRef/jabref). * [Teamscale](https://www.cqse.eu/en/teamscale/overview/) is a popular German product analyzing code quality. The analysis results are available at . +## Background literature + We strongly recommend reading following two books on code quality: * [Java by Comparison](http://java.by-comparison.com) is a book by three JabRef developers which focuses on code improvements close to single statements. It is fast to read and one gains much information from each recommendation discussed in the book. diff --git a/docs/code-howtos/error-handling.md b/docs/code-howtos/error-handling.md index 233ebd10d1c..562a74e8039 100644 --- a/docs/code-howtos/error-handling.md +++ b/docs/code-howtos/error-handling.md @@ -9,16 +9,17 @@ Principles: * All exceptions we throw should be or extend `JabRefException`; This is especially important if the message stored in the Exception should be shown to the user. `JabRefException` has already implemented the `getLocalizedMessage()` method which should be used for such cases (see details below!). * Catch and wrap all API exceptions (such as `IOExceptions`) and rethrow them - * Example: - - ```java - try { - // ... - } catch (IOException ioe) { - throw new JabRefException("Something went wrong...", - Localization.lang("Something went wrong...", ioe); - } - ``` + * Example: + + ```java + try { + // ... + } catch (IOException ioe) { + throw new JabRefException("Something went wrong...", + Localization.lang("Something went wrong...", ioe); + } + ``` + * Never, ever throw and catch `Exception` or `Throwable` * Errors should only be logged when they are finally caught (i.e., logged only once). See **Logging** for details. * If the Exception message is intended to be shown to the User in the UI (see below) provide also a localizedMessage (see `JabRefException`). @@ -34,6 +35,6 @@ To show error message two different ways are usually used in JabRef: * showing an error dialog * updating the status bar at the bottom of the main window -``` -TODO: Usage of status bar and Swing Dialogs +```text +TODO: Usage of status bar and `DialogService` ``` diff --git a/docs/code-howtos/http-server.md b/docs/code-howtos/http-server.md index 0652cbe70c0..309c3eeb30f 100644 --- a/docs/code-howtos/http-server.md +++ b/docs/code-howtos/http-server.md @@ -17,7 +17,9 @@ Howto for Windows - other operating systems work similar: Note: If you do not do this, you get following error message: - Could not find server key store C:\Users\USERNAME\AppData\Local\org.jabref\jabref\ssl\server.p12. +```text +Could not find server key store C:\Users\USERNAME\AppData\Local\org.jabref\jabref\ssl\server.p12. +``` ## Start http server @@ -33,13 +35,15 @@ Does not work. Current try: - ./gradlew run -Pcomment=httpserver +```shell +./gradlew run -Pcomment=httpserver +``` -However, there are with `ForkJoin` (discussion at https://discuss.gradle.org/t/is-it-ok-to-use-collection-parallelstream-or-other-potentially-multi-threaded-code-within-gradle-plugin-code/28003) +However, there are with `ForkJoin` (discussion at ) Gradle output: -``` +```shell > Task :run 2023-04-22 11:30:59 [main] org.jabref.http.server.Server.main() DEBUG: Libraries served: [C:\git-repositories\jabref-all\jabref\src\main\resources\org\jabref\http\server\http-server-demo.bib] @@ -51,7 +55,7 @@ DEBUG: Starting server... IntelliJ output, if `org.jabref.http.server.Server#main` is executed: -``` +```shell DEBUG: Starting server... 2023-04-22 11:44:59 [ForkJoinPool.commonPool-worker-1] org.glassfish.grizzly.http.server.NetworkListener.start() INFO: Started listener bound to [localhost:6051] diff --git a/docs/code-howtos/index.md b/docs/code-howtos/index.md index 94ca60ff51a..fff2c645b44 100644 --- a/docs/code-howtos/index.md +++ b/docs/code-howtos/index.md @@ -64,25 +64,26 @@ Global variables should be avoided. Try to pass them as dependency. ### keywords sync -Database.addDatabaseChangeListener does not work as the DatabaseChangedEvent does not provide the field information. Therefore, we have to use BibtexEntry.addPropertyChangeListener(VetoableChangeListener listener) +`Database.addDatabaseChangeListener` does not work as the `DatabaseChangedEvent` does not provide the field information. +Therefore, we have to use `BibtexEntry.addPropertyChangeListener(VetoableChangeListener listener)`. ## Working with BibTeX data ### Working with authors -You can normalize the authors using `org.jabref.model.entry.AuthorList.fixAuthor_firstNameFirst(String)`. Then the authors always look nice. The only alternative containing all data of the names is `org.jabref.model.entry.AuthorList.fixAuthor_lastNameFirst(String)`. The other `fix...` methods omit data (like the von parts or the junior information). +You can normalize the authors using `org.jabref.model.entry.AuthorList.fixAuthor_firstNameFirst(String)`. Then the authors always look nice. The only alternative containing all data of the names is `org.jabref.model.entry.AuthorList.fixAuthor_lastNameFirst(String)`. The other `fix...` methods omit data (like the "von" parts or the junior information). ## Benchmarks * Benchmarks can be executed by running the `jmh` gradle task (this functionality uses the [JMH Gradle plugin](https://github.com/melix/jmh-gradle-plugin)) * Best practices: - * Read test input from `@State` objects - * Return result of calculations (either explicitly or via a `BlackHole` object) + * Read test input from `@State` objects + * Return result of calculations (either explicitly or via a `BlackHole` object) * [List of examples](https://github.com/melix/jmh-gradle-example/tree/master/src/jmh/java/org/openjdk/jmh/samples) ## Measure performance -Try out the [YourKit JAva Profiler](https://www.yourkit.com). +Try out the [YourKit Java Profiler](https://www.yourkit.com). ## equals @@ -92,7 +93,7 @@ When creating an `equals` method follow: 2. Use the `instanceof` operator to check if the argument has the correct type. If not, return `false`. 3. Cast the argument to the correct type. 4. For each “significant” field in the class, check if that field of the argument matches the corresponding field of this object. If all these tests succeed, return `true` otherwise, return `false`. -5. When you are finished writing your equals method, ask yourself three questions: Is it symmetric? Is it transitive? Is it consistent? +5. When you are finished writing your `equals` method, ask yourself three questions: Is it symmetric? Is it transitive? Is it consistent? Also, note: @@ -103,4 +104,3 @@ Also, note: ## Files and Paths Always try to use the methods from the nio-package. For interoperability, they provide methods to convert between file and path. [https://docs.oracle.com/javase/tutorial/essential/io/path.html](https://docs.oracle.com/javase/tutorial/essential/io/path.html) Mapping between old methods and new methods [https://docs.oracle.com/javase/tutorial/essential/io/legacy.html#mapping](https://docs.oracle.com/javase/tutorial/essential/io/legacy.html#mapping) - diff --git a/docs/code-howtos/javafx.md b/docs/code-howtos/javafx.md index c5faee31d74..c045b12fc12 100644 --- a/docs/code-howtos/javafx.md +++ b/docs/code-howtos/javafx.md @@ -128,7 +128,7 @@ public class AboutDialogView extends BaseDialog @Inject private DialogService dialogService; ``` -* It is convenient to load the FXML-view directly from the controller class. +* It is convenient to load the FXML-view directly from the controller class. The FXML file is loaded using `ViewLoader` based on the name of the class passed to `view`. To make this convention-over-configuration approach work, both the FXML file and the View class should have the same name and should be located in the same package. diff --git a/docs/code-howtos/jpackage.md b/docs/code-howtos/jpackage.md index 669ce1f3242..74c10a524fd 100644 --- a/docs/code-howtos/jpackage.md +++ b/docs/code-howtos/jpackage.md @@ -28,11 +28,12 @@ Sometimes issues with modularity only arise in the installed version and do not 1. Open `build.gradle`, under jlink options remove `--strip-debug` 2. Build using `jpackageImage` (or let the CI build a new version) -3. Modify the `build\image\JabRef\runtime\bin\Jabref.bat` file, replace the last line with +3. Modify the `build\image\JabRef\runtime\bin\Jabref.bat` file, replace the last line with - ``` + ```shell pushd %DIR% & %JAVA_EXEC% -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n -p "%~dp0/../app" -m org.jabref/org.jabref.cli.Launcher %* & popd ``` + 4. Open your IDE and add a "Remote Debugging Configuration" for `localhost:8000` 5. Start JabRef by running the above bat file 6. Connect with your IDE using remote debugging diff --git a/docs/code-howtos/localization.md b/docs/code-howtos/localization.md index c9072e21494..f2da0d5950e 100644 --- a/docs/code-howtos/localization.md +++ b/docs/code-howtos/localization.md @@ -35,9 +35,7 @@ General hints: The tests check whether translation strings appear correctly in the resource bundles. -1. Add new `Localization.lang("KEY")` to Java file. Run the `LocalizationConsistencyTest`under (src/test/org.jabref.logic. - - ) +1. Add new `Localization.lang("KEY")` to Java file. Run the `org.jabref.logic.LocalizationConsistencyTest`. 2. Tests fail. In the test output a snippet is generated which must be added to the English translation file. 3. Add snippet to English translation file located at `src/main/resources/l10n/JabRef_en.properties` 4. Please do not add translations for other languages directly in the properties. They will be overwritten by [Crowdin](https://crowdin.com/project/jabref) diff --git a/docs/code-howtos/logging.md b/docs/code-howtos/logging.md index 09b252b525e..4503d0731fb 100644 --- a/docs/code-howtos/logging.md +++ b/docs/code-howtos/logging.md @@ -43,6 +43,5 @@ In the `.properties` file, this is done for `org.jabref.model.entry.BibEntry`. ## Further reading -SLF4J also support parameterized logging, e.g. if you want to print out multiple arguments in a log statement use a pair of curly braces (`{}`). +SLF4J also support parameterized logging, e.g. if you want to print out multiple arguments in a log statement use a pair of curly braces (`{}`). Head to for examples. - diff --git a/docs/code-howtos/openoffice/ooresult-ooerror/index.md b/docs/code-howtos/openoffice/ooresult-ooerror/index.md index 3260928b9b3..fd43f56efb1 100644 --- a/docs/code-howtos/openoffice/ooresult-ooerror/index.md +++ b/docs/code-howtos/openoffice/ooresult-ooerror/index.md @@ -99,7 +99,7 @@ with an assumption that at any time exactly one of `result` and `error` is prese * Since `OOResult` encodes the state `isOK` in `result.isPresent()` (and equivalently in `errror.isEmpty()`), we cannot allow construction of instances where both values are `isEmpty`.\ In particular, `OOResult.ok(null)` and `OOResult.error(null)` are not allowed: it would make the state `isOK` ambiguous.\ It would also break the similarity to `Optional` to allow both `isEmpty` and `isOK` to be true. -* Not allowing null, has a consequence on `OOResult`\ +* Not allowing null, has a consequence on `OOResult`\ According to [baeldung.com/java-void-type](https://www.baeldung.com/java-void-type), the only possible value for `Void` is `null` which we excluded. `OOResult.ok(null)` would look strange: in this case we need `ok()` without arguments. diff --git a/docs/code-howtos/openoffice/overview.md b/docs/code-howtos/openoffice/overview.md index 56ec4d857ce..a76ece7bb3a 100644 --- a/docs/code-howtos/openoffice/overview.md +++ b/docs/code-howtos/openoffice/overview.md @@ -65,7 +65,7 @@ A group of parenthesized citations share the parentheses around, like this:\ From the user's point of view, citation groups can be created by -1. Selecting multiple entries in a bibliography database, then +1. Selecting multiple entries in a bibliography database, then * `[click:Cite]` or * `[click:Cite in-text]` or @@ -140,8 +140,8 @@ The order of appearance of citations (as considered during numbering and adding The order of citations within a citation group is controlled by `jstyle:MultiCiteChronological`. -* true asks for (year, author, title) ordering, -* false for (author, year, title). +* `true` asks for (year, author, title) ordering, +* `false` for (author, year, title). * (There is no option for "in the order provided by the user"). For author-year citation styles this ordering is used directly. @@ -159,21 +159,21 @@ The location of each citation group in the document is provided by the user. In #### Order of the citations * `globalOrder` and `localOrder` together provide the order of appearance of citations -* This also provides the order of first appearance of the cited sources. +* This also provides the order of first appearance of the cited sources. - First appearance order of sources is used + First appearance order of sources is used - * in `jstyle:IsSortByPosition` numbered styles - * in author-year styles: first appearance of "Smith200a" should precede that of "Smith200b".\ - To achieve this, the sources get the letters according the order of their first appearance. - * This seems to contradict the statement "The bibliography is sorted in (author, year, title) order" above.\ - It does not. As of JabRef 5.3 both are true.\ - Consequence: in the references Smith2000b may precede Smith2000a. ([reported](https://github.com/JabRef/jabref/issues/7805)) - * Some author-year citation styles prescribe a higher threshold on the number of authors for switching to "FirstAuthor et al." form (`jstyle:MaxAuthors`) at the first citation of a source (`jstyle:MaxAuthorsFirst`) + * in `jstyle:IsSortByPosition` numbered styles + * in author-year styles: first appearance of "Smith200a" should precede that of "Smith200b".\ + To achieve this, the sources get the letters according the order of their first appearance. + * This seems to contradict the statement "The bibliography is sorted in (author, year, title) order" above.\ + It does not. As of JabRef 5.3 both are true.\ + Consequence: in the references Smith2000b may precede Smith2000a. ([reported](https://github.com/JabRef/jabref/issues/7805)) + * Some author-year citation styles prescribe a higher threshold on the number of authors for switching to "FirstAuthor et al." form (`jstyle:MaxAuthors`) at the first citation of a source (`jstyle:MaxAuthorsFirst`) ## What is stored in a document (JabRef5.2) -* Each group of citations has a reference mark. +* Each group of citations has a reference mark. (Reference marks are shown in LibreOffice in Navigator, under "References".\ To show the Navigator: `LibreOffice:[menu:View]/[Navigator]` or `LibreOffice:[key:F5]`) diff --git a/docs/code-howtos/openoffice/problems.md b/docs/code-howtos/openoffice/problems.md index 4d11dc62966..ee371a72d36 100644 --- a/docs/code-howtos/openoffice/problems.md +++ b/docs/code-howtos/openoffice/problems.md @@ -11,22 +11,22 @@ grand_parent: Code Howtos a `(problem)`: pageInfo strings are conceptually associated with citations, but the implementation associates them to citation groups.\ The number of available pageInfo slots changes during`[click:Merge]` and `[click:Separate]` while the number of citations remains fixed. * The proposed solution was to change the association. - * Not only reference marks (citation groups) need unique identifiers, but also citations.\ - Possible encoding for reference mark names:\ - `JR_cite{type}_{number1}_{citationKey1},{number2}_{citationKey2}`\ - where `{type}` encodes the citation type (for the group), `{citationKey1}` is made unique by choosing an appropriate number for `{number1}`\ - This would allow `JR_cite_{number1}_{citationKey1}` to be used as a property name for storing the pageInfo. + * Not only reference marks (citation groups) need unique identifiers, but also citations.\ + Possible encoding for reference mark names:\ + `JR_cite{type}_{number1}_{citationKey1},{number2}_{citationKey2}`\ + where `{type}` encodes the citation type (for the group), `{citationKey1}` is made unique by choosing an appropriate number for `{number1}`\ + This would allow `JR_cite_{number1}_{citationKey1}` to be used as a property name for storing the pageInfo. - Changes required to + Changes required to - * reference mark search, name generation and parsing - * name generation and parsing for properties storing pageInfo values - * in-memory representation - * JabRef 5.2 does not collect pageInfo values, accesses only when needed.\ - So it would be change to code accessing them. - * The proposed representation does collect, to allow separation of getting from the document and processing - * insertion of pageInfo into citation markers: JabRef 5.2 injects a single pageInfo before the closing parenthesis, now we need to handle several values - * `[click:Manage citations]` should work on citations, not citation groups. + * reference mark search, name generation and parsing + * name generation and parsing for properties storing pageInfo values + * in-memory representation + * JabRef 5.2 does not collect pageInfo values, accesses only when needed.\ + So it would be change to code accessing them. + * The proposed representation does collect, to allow separation of getting from the document and processing + * insertion of pageInfo into citation markers: JabRef 5.2 injects a single pageInfo before the closing parenthesis, now we need to handle several values + * `[click:Manage citations]` should work on citations, not citation groups. ## Backend diff --git a/docs/code-howtos/testing.md b/docs/code-howtos/testing.md index 3a4831353a4..bd882884954 100644 --- a/docs/code-howtos/testing.md +++ b/docs/code-howtos/testing.md @@ -24,7 +24,7 @@ Imagine you want to test the method `format(String value)` in the class `BracesF * _Placing:_ all tests should be placed in a class named `classTest`, e.g. `BracesFormatterTest`. * _Naming:_ the name should be descriptive enough to describe the whole test. Use the format `methodUnderTest_ expectedBehavior_context` (without the dashes). So for example `formatRemovesDoubleBracesAtBeginning`. Try to avoid naming the tests with a `test` prefix since this information is already contained in the class name. Moreover, starting the name with `test` leads often to inferior test names (see also the [Stackoverflow discussion about naming](http://stackoverflow.com/questions/155436/unit-test-naming-best-practices)). -* _Test only one thing per test:_ tests should be short and test only one small part of the method. So instead of +* _Test only one thing per test:_ tests should be short and test only one small part of the method. So instead of ```java testFormat() { @@ -36,14 +36,14 @@ Imagine you want to test the method `format(String value)` in the class `BracesF we would have five tests containing a single `assert` statement and named accordingly (`formatDoesNotChangeStringWithoutBraces`, `formatDoesNotRemoveSingleBrace`, , etc.). See [JUnit AntiPattern](https://exubero.com/junit/anti-patterns/#Multiple\_Assertions) for background. * Do _not just test happy paths_, but also wrong/weird input. -* It is recommend to write tests _before_ you actually implement the functionality (test driven development). +* It is recommended to write tests _before_ you actually implement the functionality (test driven development). * _Bug fixing:_ write a test case covering the bug and then fix it, leaving the test as a security that the bug will never reappear. * Do not catch exceptions in tests, instead use the `assertThrows(Exception.class, ()->doSomethingThrowsEx())` feature of [junit-jupiter](https://junit.org/junit5/docs/current/user-guide/) to the test method. ## Lists in tests * Use `assertEquals(Collections.emptyList(), actualList);` instead of `assertEquals(0, actualList.size());` to test whether a list is empty. -* Similarly, use `assertEquals(Arrays.asList("a", "b"), actualList);` to compare lists instead of +* Similarly, use `assertEquals(Arrays.asList("a", "b"), actualList);` to compare lists instead of ```java assertEquals(2, actualList.size()); @@ -57,7 +57,7 @@ Imagine you want to test the method `format(String value)` in the class `BracesF ## Files and folders in tests -* If you need a temporary file in tests, then add the following Annotation before the class: +* If you need a temporary file in tests, then add the following Annotation before the class: ```java @ExtendWith(TempDirectory.class) @@ -112,7 +112,7 @@ To test that a preferences migration works successfully, use the mockito method To quickly host a local PostgreSQL database, execute following statement: -``` +```shell docker run -d -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres -p 5432:5432 --name db postgres:10 postgres -c log_statement=all ``` @@ -124,7 +124,7 @@ Then, all DBMS Tests (annotated with `@org.jabref.testutils.category.DatabaseTes A MySQL DBMS can be started using following command: -``` +```shell docker run -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=jabref -p 3800:3307 mysql:8.0 --port=3307 ``` diff --git a/docs/contributing.md b/docs/contributing.md index 3d010158623..bd187bf1f3f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -18,11 +18,12 @@ We welcome contributions to JabRef and encourage you to follow the GitHub workfl 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 `main` branch.** Refer to our [code how-tos](https://devdocs.jabref.org/getting-into-the-code/code-howtos) if you have questions about your implementation. +3. Work on the **new branch — not the `main` branch.** Refer to our [code how-tos](https://devdocs.jabref.org/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. +5. In case your pull request is not yet complete or not yet ready for review, create 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, please comment on the issue - or show up in our [gitter chat](https://gitter.im/JabRef/jabref). +Please also help others in case of general questions there. ### Formal requirements for a pull request @@ -65,7 +66,7 @@ Add new `Localization.lang("KEY")` to a Java file. The tests will fail. In the t Example: -``` +```text java.lang.AssertionError: DETECTED LANGUAGE KEYS WHICH ARE NOT IN THE ENGLISH LANGUAGE FILE PASTE THESE INTO THE ENGLISH LANGUAGE FILE [ @@ -91,7 +92,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 the following template (based on [sustainable architectural decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions)): -``` +```text In the context of , facing we decided for