From 6cd7a719d152912b7474eaf03b4475e026c2814d Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 30 May 2025 12:41:26 +0200 Subject: [PATCH 1/6] More easy run --- en/contributing/README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/en/contributing/README.md b/en/contributing/README.md index 02f6b6975..d0ed6e73c 100644 --- a/en/contributing/README.md +++ b/en/contributing/README.md @@ -51,21 +51,28 @@ Now you are all set: You have a directory `jabref` containing the recent updates ### Try a branch 1. `cd` into the `jabref` source directory: `cd c:\git-repositories\jabref` -2. Checkout out the pull request: `sh ./gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CheckoutPR.java 13182` - where `13182` is the PR number, in this case [pr#13182](https://github.com/JabRef/jabref/pull/13182). +2. Checkout the PR and run JabRef: `sh ./gg.cmd gh/casey/just run-pr xyz` - replace `xyz` with the PR number or the unique branch identifier by GitHub - - Instead of the number, you can also copy and paste the branch identifier output by GitHub: `sh ./gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CheckoutPR.java Yubo-Cao:walkthrough`. + - Example: `13182` for [pr#13182](https://github.com/JabRef/jabref/pull/13182). + - Example: `Yubo-Cao:walkthroug` for the branch identifier output by GitHub ![pr-13182](../.gitbook/assets/pr-13182.png) -3. Compile and run JabRef: `sh ./gg.cmd gradle run :jabgui:run`. This will also download the necessary JDK and a gradle distribution. On the first run, please give the system enough time to accommodate and wait until the JabRef window launches. Depending on your hardware, this may take a few minutes. +This will download the necessary JDK and a gradle distribution. +On the first run, please give the system enough time to accommodate and wait until the JabRef window launches. +Depending on your hardware, this may take a few minutes. On Windows, instead of `sh ./gg.cmd` use `.\gg.cmd`. #### Alternatives -1. In case you don't want to use `gg.cmd`: You can install [JBang](https://www.jbang.dev/) for yourself and execute the commands directly. +1. In case you don't want to use `gg.cmd`: You can install [JBang](https://www.jbang.dev/) and a [Java JDK](https://adoptium.net/de/temurin/releases/?os=any&arch=any&version=21)for yourself and execute the commands directly. These are + + - `jbang https://github.com/JabRef/jabref/blob/main/.jbang/CheckoutPR.java {{pr-id}}` + - `./gradlew :jabgui:run` + 2. In case you don't want to use `JBang`: - - You have the project clone ready and have some Java JDK available: In the `JabRef` directory, execute `./gradlew run`. + - You have the project clone ready and have some Java JDK available: In the `jabref` directory, execute `./gradlew run`. - Install `gh` (the [GitHub CLI](https://cli.github.com/), a command-line client for GitHub) by using the installer linked on their [homepage](https://cli.github.com/) or the commands given at the [installation hints](https://github.com/cli/cli#installation). 3. In case you don't want to use `gh`: You can use the "usual" `git clone ...`, `git remote add ...`, `git fetch ...`, and `git checkout ...` commands to checkout a pull request from a fork. From ff6dec0a5543ee0ba8b3f856d23b3c349f4844ae Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 30 May 2025 12:45:56 +0200 Subject: [PATCH 2/6] Try to have image on next line --- en/contributing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/contributing/README.md b/en/contributing/README.md index d0ed6e73c..fc182e44a 100644 --- a/en/contributing/README.md +++ b/en/contributing/README.md @@ -54,7 +54,7 @@ Now you are all set: You have a directory `jabref` containing the recent updates 2. Checkout the PR and run JabRef: `sh ./gg.cmd gh/casey/just run-pr xyz` - replace `xyz` with the PR number or the unique branch identifier by GitHub - Example: `13182` for [pr#13182](https://github.com/JabRef/jabref/pull/13182). - - Example: `Yubo-Cao:walkthroug` for the branch identifier output by GitHub + - Example: `Yubo-Cao:walkthroug` for the branch identifier output by GitHub\ ![pr-13182](../.gitbook/assets/pr-13182.png) This will download the necessary JDK and a gradle distribution. From 558875c085de7be0d4b7a25200f77799cecf397c Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 30 May 2025 13:14:37 +0200 Subject: [PATCH 3/6] Use "just" instead of "gh/casey/just" --- en/contributing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/contributing/README.md b/en/contributing/README.md index fc182e44a..061d1487e 100644 --- a/en/contributing/README.md +++ b/en/contributing/README.md @@ -51,7 +51,7 @@ Now you are all set: You have a directory `jabref` containing the recent updates ### Try a branch 1. `cd` into the `jabref` source directory: `cd c:\git-repositories\jabref` -2. Checkout the PR and run JabRef: `sh ./gg.cmd gh/casey/just run-pr xyz` - replace `xyz` with the PR number or the unique branch identifier by GitHub +2. Checkout the PR and run JabRef: `sh ./gg.cmd just run-pr xyz` - replace `xyz` with the PR number or the unique branch identifier by GitHub - Example: `13182` for [pr#13182](https://github.com/JabRef/jabref/pull/13182). - Example: `Yubo-Cao:walkthroug` for the branch identifier output by GitHub\ From fd0e93667907bce91cce75b08a38bf30a792fe8c Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 30 May 2025 22:59:49 +0200 Subject: [PATCH 4/6] Update en/contributing/README.md Co-authored-by: Subhramit Basu --- en/contributing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/contributing/README.md b/en/contributing/README.md index 061d1487e..1fad7ab44 100644 --- a/en/contributing/README.md +++ b/en/contributing/README.md @@ -65,7 +65,7 @@ On Windows, instead of `sh ./gg.cmd` use `.\gg.cmd`. #### Alternatives -1. In case you don't want to use `gg.cmd`: You can install [JBang](https://www.jbang.dev/) and a [Java JDK](https://adoptium.net/de/temurin/releases/?os=any&arch=any&version=21)for yourself and execute the commands directly. These are +1. In case you don't want to use `gg.cmd`: You can install [JBang](https://www.jbang.dev/) and a [Java JDK](https://adoptium.net/de/temurin/releases/?os=any&arch=any&version=21) for yourself and execute the commands directly. These are - `jbang https://github.com/JabRef/jabref/blob/main/.jbang/CheckoutPR.java {{pr-id}}` - `./gradlew :jabgui:run` From 98e2f711e147cfaf250bda0d22acb4cb27e7b385 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sat, 31 May 2025 22:36:51 +0200 Subject: [PATCH 5/6] Refine README.md --- en/contributing/README.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/en/contributing/README.md b/en/contributing/README.md index 1fad7ab44..670d74a0a 100644 --- a/en/contributing/README.md +++ b/en/contributing/README.md @@ -25,9 +25,11 @@ In the following, we try to give a minimal set of installation instructions to b - `cd c:\git-repositories` - Get `gg.cmd` - `wget ggcmd.io -OutFile gg.cmd` + - Have JBang trusting JabRef's code + - `.\gg.cmd jbang trust add https://github.com/JabRef/jabref/` - Clone JabRef - `.\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java jabref` - - When JBang asks you for trust, you can choose "Trust once" by pressing 1 and then Enter + - NOTE: You can also use the native git client: `git clone --recurse-submodules https://github.com/JabRef/jabref.git` for achieving the same result. - Make `gg.cmd` available in `jabref` source directory - `cd jabref` - `move ..\gg.cmd .` @@ -39,19 +41,23 @@ In the following, we try to give a minimal set of installation instructions to b - Get `gg.cmd` (using either `wget` or `curl`) - `wget ggcmd.io/gg.cmd` - Alternative: `curl -L ggcmd.io > gg.cmd` + - Have JBang trusting JabRef's code + - `sh ./gg.cmd jbang trust add https://github.com/JabRef/jabref/` - Clone JabRef - `sh ./gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java jabref` - - NOTE: You can also use the native git client: `git clone --recurse-submodules https://github.com/JabRef/jabref.git jabref` for achieving the same result. + - NOTE: You can also use the native git client: `git clone --recurse-submodules https://github.com/JabRef/jabref.git` for achieving the same result. - Make `gg.cmd` available in `jabref` source directory - `cd jabref` - `mv ../gg.cmd .` Now you are all set: You have a directory `jabref` containing the recent updates and also `gg.cmd` which you will need later for executing a JabRef build. +Note: If you don't want to store JabRef's source code permanently, you can follow the steps at [our blog post on gg.cmd usage](https://blog.jabref.org/2025/05/31/run-pr/). There, JabRef's source is checked out in a temporary directory. + ### Try a branch 1. `cd` into the `jabref` source directory: `cd c:\git-repositories\jabref` -2. Checkout the PR and run JabRef: `sh ./gg.cmd just run-pr xyz` - replace `xyz` with the PR number or the unique branch identifier by GitHub +2. Checkout the PR and run JabRef: `sh ./gg.cmd just run-pr ` - replace `` with the PR number or the unique branch identifier by GitHub - Example: `13182` for [pr#13182](https://github.com/JabRef/jabref/pull/13182). - Example: `Yubo-Cao:walkthroug` for the branch identifier output by GitHub\ @@ -61,18 +67,20 @@ This will download the necessary JDK and a gradle distribution. On the first run, please give the system enough time to accommodate and wait until the JabRef window launches. Depending on your hardware, this may take a few minutes. -On Windows, instead of `sh ./gg.cmd` use `.\gg.cmd`. +On Windows, instead of `sh ./gg.cmd` use `.\gg.cmd`: + + .\gg.cmd just run-pr #### Alternatives -1. In case you don't want to use `gg.cmd`: You can install [JBang](https://www.jbang.dev/) and a [Java JDK](https://adoptium.net/de/temurin/releases/?os=any&arch=any&version=21) for yourself and execute the commands directly. These are +1. In case you don't want to use `gg.cmd`: You can install [JBang](https://www.jbang.dev/) for yourself and execute the commands directly. These are - - `jbang https://github.com/JabRef/jabref/blob/main/.jbang/CheckoutPR.java {{pr-id}}` + - `jbang https://github.com/JabRef/jabref/blob/main/.jbang/CheckoutPR.java ` - `./gradlew :jabgui:run` 2. In case you don't want to use `JBang`: - - You have the project clone ready and have some Java JDK available: In the `jabref` directory, execute `./gradlew run`. + - You have the project clone ready and have some [Java JDK](https://adoptium.net/de/temurin/releases/?os=any&arch=any&version=21) available: In the `jabref` directory, execute `./gradlew run`. - Install `gh` (the [GitHub CLI](https://cli.github.com/), a command-line client for GitHub) by using the installer linked on their [homepage](https://cli.github.com/) or the commands given at the [installation hints](https://github.com/cli/cli#installation). 3. In case you don't want to use `gh`: You can use the "usual" `git clone ...`, `git remote add ...`, `git fetch ...`, and `git checkout ...` commands to checkout a pull request from a fork. From e757bb665aba901c2583c6d7c11f87cc87179a93 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sun, 1 Jun 2025 00:10:27 +0200 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Subhramit Basu --- en/contributing/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/en/contributing/README.md b/en/contributing/README.md index 670d74a0a..6d43af905 100644 --- a/en/contributing/README.md +++ b/en/contributing/README.md @@ -25,11 +25,11 @@ In the following, we try to give a minimal set of installation instructions to b - `cd c:\git-repositories` - Get `gg.cmd` - `wget ggcmd.io -OutFile gg.cmd` - - Have JBang trusting JabRef's code + - Have JBang trust JabRef's source - `.\gg.cmd jbang trust add https://github.com/JabRef/jabref/` - Clone JabRef - `.\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java jabref` - - NOTE: You can also use the native git client: `git clone --recurse-submodules https://github.com/JabRef/jabref.git` for achieving the same result. + - NOTE: You can also use the native git client: `git clone --recurse-submodules https://github.com/JabRef/jabref.git` to achieve the same result. - Make `gg.cmd` available in `jabref` source directory - `cd jabref` - `move ..\gg.cmd .` @@ -41,11 +41,11 @@ In the following, we try to give a minimal set of installation instructions to b - Get `gg.cmd` (using either `wget` or `curl`) - `wget ggcmd.io/gg.cmd` - Alternative: `curl -L ggcmd.io > gg.cmd` - - Have JBang trusting JabRef's code + - Have JBang trust JabRef's source - `sh ./gg.cmd jbang trust add https://github.com/JabRef/jabref/` - Clone JabRef - `sh ./gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java jabref` - - NOTE: You can also use the native git client: `git clone --recurse-submodules https://github.com/JabRef/jabref.git` for achieving the same result. + - NOTE: You can also use the native git client: `git clone --recurse-submodules https://github.com/JabRef/jabref.git` to achieve the same result. - Make `gg.cmd` available in `jabref` source directory - `cd jabref` - `mv ../gg.cmd .` @@ -60,7 +60,7 @@ Note: If you don't want to store JabRef's source code permanently, you can follo 2. Checkout the PR and run JabRef: `sh ./gg.cmd just run-pr ` - replace `` with the PR number or the unique branch identifier by GitHub - Example: `13182` for [pr#13182](https://github.com/JabRef/jabref/pull/13182). - - Example: `Yubo-Cao:walkthroug` for the branch identifier output by GitHub\ + - Example: `Yubo-Cao:walkthrough` for the branch identifier output by GitHub\ ![pr-13182](../.gitbook/assets/pr-13182.png) This will download the necessary JDK and a gradle distribution.