Add gg.cmd run-pr xyz (#115)

Co-authored-by: Subhramit Basu <subhramit.bb@live.in>

Author: koppor

_posts/2025-05-31-run-pr.md

@@ -0,0 +1,102 @@
+---
+title: How to try out any JabRef pull request
+---
+
+JabRef gets many contributions by external contributors in the form of [pull requests](https://github.com/jabref/jabref/pulls).
+Want to try out the feature or fix?
+You can now do so in a few simple steps, and give early feedback!
+
+For instance, to try out the "[initial implementation of walkthrough](https://github.com/JabRef/jabref/pull/13182)", one needs to execute following command:
+
+- Windows: `.\gg.cmd just run-pr 13182`
+- macOS/Linux: `sh ./gg.cmd just run-pr 13182`
+
+## Preparation
+
+To make this work, one needs to have [`gg.cmd`](https://github.com/eirikb/gg#ggcmd) available in JabRef's source directory.
+
+This can be achieved by using `gg.cmd`, `JBang`, and scripts offered by JabRef:
+
+1. [Download `gg.cmd`](https://github.com/eirikb/gg/releases/latest/download/gg.cmd)
+2. Instruct `JBang` to trust JabRef: Execute `.\gg.cmd jbang trust add https://github.com/JabRef/jabref/`.\
+   ![gg initialization](../img/gg-init-1.png)\
+   ![gg initialization](../img/gg-init-2.png)
+3. Clone JabRef into a folder.
+   By default, a system-wide available temporary folder is used.
+   (In "Advanced Hints" below, we mention steps on how to use a specific folder.)
+   Execute `.\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java`.\
+   ![gg-jabref-clone](../img/gg-jabref-clone.png)
+4. After it finishes, it will output the directory:
+
+   ```text
+   JabRef code available at: C:\Users\WDAGUtilityAccount\AppData\Local\Temp\jabref
+   ```
+
+5. Go to the directory: `cd C:\Users\WDAGUtilityAccount\AppData\Local\Temp\jabref` (Note - replace "`WDAGUtilityAccount`" with your username).
+6. Move `gg.cmd` to here: `move C:\Users\WDAGUtilityAccount\Downloads\gg.cmd .`. (Note - replace "`WDAGUtilityAccount`" with your username. The path also needs to be changed if you have downloaded `gg.cmd` anywhere else.)
+7. Now you can run a PR using `.\gg.cmd just run-pr 13182` (replace `13182` with the PR number of whichever PR you want to try out). Initially, this might take several minutes, as the build environment has to be initialized and JabRef is built completely from scratch. In subsequent runs, the process is much faster.
+
+## Advanced Hints
+
+### Using another directory
+
+In step 3, a temporary folder was used.
+You can also use a different directory.
+For example, following command clones into a directory `jabref` located in the current folder:
+
+```cmd
+.\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java jabref
+```
+
+In general, any (non-existing) directory can be used.
+To clone into `c:\git-repositories\jabref`, use following command:
+
+```cmd
+.\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java c:\git-repositories\jabref
+```
+
+### Linux and macOS
+
+For Linux and macOS, use `sh ./gg.cmd` instead of `.\gg.cmd`.
+
+### Running `JabKit`
+
+You can run other parts of JabRef. For instance for `JabKit`:
+
+```cmd
+.\gg.cmd just run-jabkit --help
+```
+
+### Using a Windows Sandbox
+
+[Windows Sandbox](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/) is a nice feature to run a clean Windows system and have it deleted after use.
+
+There is [CustomSandbox](https://github.com/oOblik/CustomSandbox) with a nice Terminal-based UI to configure the Sandbox.
+We modified it to include `gg.cmd`.
+To use, follow these steps:
+
+1. Download <https://github.com/koppor/CustomSandbox/archive/refs/heads/main.zip>
+2. Extract it.
+3. Start "PowerShell".
+4. `cd` into the directory where you extraced it.
+5. Start the script: `.\CustomSandbox.ps1`.
+6. In the first screen, enable `[x] Networking` and `[x] Save Configuration`.
+7. In the second screen, enable `[x] [Chocolatey] Microsoft VC++ Redist for VS 2015-2022`, because this is required for JabRef's AI functionality. It will also enable some other packages required for installation.
+8. Also enable `[x] Download gg.cmd`.
+9. After pressing <kbd>Enter</kbd>, dependencies will be downloaded.
+10. Afterwards, one has to press <kbd>Enter</kbd> again to launch the sandbox.
+11. There, the chosen dependencies will be installed.
+12. Now, you can start PowerShell and continue with step 2 from above to instruct `JBang` to trust JabRef's code.
+
+As usual, the first run takes a long time, because it will download all required files.
+The second run will be faster, because the files are cached.
+
+## Special Thanks
+
+- [`gg.cmd`](https://github.com/eirikb/gg#ggcmd) for automatic downloading and execution of required tooling.
+- [`JBang`](https://www.jbang.dev/) for enabling easy execution of `.java` files.
+- [Eclipse JGit](https://projects.eclipse.org/projects/technology.jgit) for making `git` available as pure Java library.
+
+## More Information
+
+More information is available in our [contributing guide](https://docs.jabref.org/contributing#i-would-like-to-try-out-a-feature-introduced-at-pull-request).