Refine documentation (#12972)

koppor · subhramit · web-flow · commit 4916a012a408 · 2025-04-21T08:50:26.000Z
* Refine grammar in README.md

* Fix grammar

* Move FAQ to FAQs

* Move getting-into-the-code/* into either /index.md or code-howtos/*

* Fix markdown

* Re-refinement

* Fix link

* Refine builds information

---------

Co-authored-by: Subhramit Basu &lt;subhramit.bb@live.in&gt;
diff --git a/README.md b/README.md
@@ -59,15 +59,15 @@ Please see our [Installation Guide](https://docs.jabref.org/installation).
 
 We are thankful for any bug reports or other feedback.
 If you have ideas for new features you want to be included in JabRef, tell us in [the feature section](http://discourse.jabref.org/c/features) of our forum!
-If you need support in using JabRef, please read [the documentation](https://docs.jabref.org/) first, the [frequently asked questions (FAQ)](https://docs.jabref.org/faq) and also have a look at our [community forum](https://discourse.jabref.org/c/help/7).
+If you need support in using JabRef, please read the [user documentation](https://docs.jabref.org/), especially the [frequently asked questions (FAQ)](https://docs.jabref.org/faq) and also take a look at our [community forum](https://discourse.jabref.org/c/help/7).
 You can use our [GitHub issue tracker](https://github.com/JabRef/jabref/issues) to file bug reports.
 
 An explanation of donation possibilities and usage of donations is available at our [donations page](https://donations.jabref.org).
 
 ## Contributing
 
 Want to be part of a free and open-source project that tens of thousands of researchers use every day?
-Please have a look at our [guidelines for contributing](CONTRIBUTING.md).
+Please take a look at our [guidelines for contributing](CONTRIBUTING.md).
 
 ## Research and Education
 
diff --git a/docs/code-howtos/cli.md b/docs/code-howtos/cli.md
@@ -0,0 +1,14 @@
+---
+parent: Code Howtos
+---
+# Command Line Interface
+
+The package `org.jabref.cli` is responsible for handling the command line options.
+
+During development, one can configure IntelliJ to pass command line parameters:
+
+![IntelliJ-run-configuration](../images/intellij-run-configuration-command-line.png)
+
+Passing command line arguments using gradle is currently not possible as all arguments (such as `-Dfile.encoding=windows-1252`) are passed to the application.
+
+Without [jlink](https://docs.oracle.com/en/java/javase/11/tools/jlink.html), it is not possible to generate a fat jar anymore. During development, the capabilities of the IDE has to be used.
diff --git a/docs/code-howtos/faq.md b/docs/code-howtos/faq.md
@@ -5,6 +5,11 @@ parent: Code Howtos
 
 Following is a list of common errors encountered by developers which lead to failing tests, with their common solutions:
 
+## git hints
+
+* Sync your fork with the JabRef repository: [General howto by GitHub](https://help.github.com/articles/syncing-a-fork/)
+* Branches and pull requests (🇩🇪): [https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week2/exercises/practical-exercises.md](https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week2/exercises/practical-exercises.md)
+
 ## Failing tests
 
 ### Failing <b>Checkstyle</b> tests
@@ -149,4 +154,10 @@ And similarly for `csl-locales` or `abbrv.jabref.org`.
 
 To avoid this, avoid staging using `git add .` from CLI. Preferably use a GUI-based git manager, such as the one built in IntelliJ or open git gui from the command line. Even if you accidentally stage them, don't commit all files, selectively commit the files you touched using the GUI based tool, and push.
 
+## Q: I get `java: package org.jabref.logic.journals does not exist`
+
+A: You have to ignore `buildSrc/src/main` as source directory in IntelliJ as indicated in our [setup guide](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace).
+
+Also filed as IntelliJ issue [IDEA-240250](https://youtrack.jetbrains.com/issue/IDEA-240250).
+
 <!-- markdownlint-disable-file MD033 -->
diff --git a/docs/code-howtos/groups.md b/docs/code-howtos/groups.md
@@ -0,0 +1,6 @@
+---
+parent: Code Howtos
+---
+# Groups
+
+Diagram showing aspects of groups: [Groups.uml](https://github.com/JabRef/jabref/tree/3b3716b1e05a0d3273c886e102a8efe5e96472e0/docs/Groups.uml).
diff --git a/docs/code-howtos/index.md b/docs/code-howtos/index.md
@@ -62,7 +62,7 @@ This is implemented in `FileUtil`:
 org.jabref.logic.util.io.FileUtil.relativize(java.nio.file.Path, org.jabref.model.database.BibDatabaseContext, org.jabref.logic.FilePreferences)
 ```
 
-## Setting a Directory for a .bib File
+## Setting a directory for a `.bib` file
 
 * `@comment{jabref-meta: fileDirectory:<directory>`
 * “fileDirectory” is determined by Globals.pref.get(“userFileDir”) (which defaults to “fileDirectory”
diff --git a/docs/getting-into-the-code/development-strategy.md b/docs/getting-into-the-code/development-strategy.md
diff --git a/docs/getting-into-the-code/high-level-documentation.md b/docs/getting-into-the-code/high-level-documentation.md
diff --git a/docs/index.md b/docs/index.md
@@ -5,53 +5,99 @@ layout: home
 # Overview on Developing JabRef
 
 This page presents all development information around JabRef.
-In case you are a end user, please head to the [user documentation](https://docs.jabref.org) or to the [general homepage](https://www.jabref.org) of JabRef.
+In case you are an end user, please head to the [user documentation](https://docs.jabref.org) or to the [general homepage](https://www.jabref.org) of JabRef.
 
 ## Starting point for new developers
 
 On the page [Setting up a local workspace](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace), we wrote about the initial steps to get your IDE running.
-We strongly recommend to continue reading there.
+We strongly recommend continuing reading there.
 After you successfully cloned and build JabRef, you are invited to continue reading here.
 
-## How tos
+## JabRef's development strategy
 
-* External: [Sync your fork with the JabRef repository](https://help.github.com/articles/syncing-a-fork/)
-* External (🇩🇪): Branches and pull requests: [https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week2/exercises/practical-exercises.md](https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week2/exercises/practical-exercises.md)
+We aim to keep up to high-quality code standards and use code quality tools wherever possible.
 
-## Teaching Exercises
+To ensure high code-quality,
 
-We are very happy that JabRef is part of [Software Engineering](https://en.wikipedia.org/wiki/Software_engineering) trainings. Please head to [Teaching](teaching.md) for more information on using JabRef as a teaching object and on previous courses where JabRef was used.
+* We follow the principles of [Java by Comparison](https://java.by-comparison.com).
+* We follow the principles of [Effective Java](https://www.oreilly.com/library/view/effective-java-3rd/9780134686097/).
+* We use [Design Patterns](https://java-design-patterns.com/patterns/) when applicable.
+* We document our design decisions using the lightweight architectural decision records [MADR](https://adr.github.io/madr/).
+* Each external pull request is reviewed by at least two [JabRef Core Developers](https://github.com/JabRef/jabref/blob/main/MAINTAINERS).
 
-## Miscellaneous Hints
+## Continuous integration
 
-### Command Line
+JabRef has automatic checks using [GitHub actions](https://github.com/features/actions) in place.
+One of them is checking for proper formatting of the code.
+Consistent formatting ensures easier reading of the code.
+Thus, we ensure that all of JabRef's code follows the same code style.
 
-The package `org.jabref.cli` is responsible for handling the command line options.
+Binaries are created using [gradle](https://gradle.org).
+In case of an internal pull request, they are uploaded to <https://builds.jabref.org>.
+These binaries are created without any checks to have them available as quickly as possible, even if the localization or some fetchers are broken.
+You can fnd the deployment workflow runs at: <https://github.com/JabRef/jabref/actions?workflow=Deployment>.
 
-During development, one can configure IntelliJ to pass command line parameters:
+## Branches
 
-![IntelliJ-run-configuration](images/intellij-run-configuration-command-line.png)
+The [main](https://github.com/JabRef/jabref/tree/main) branch is the main development line ("trunk") and is intended to incorporate fixes and improvements as soon as possible and to move JabRef forward to modern technologies such as the latest Java version.
 
-Passing command line arguments using gradle is currently not possible as all arguments (such as `-Dfile.encoding=windows-1252`) are passed to the application.
+Other branches are used for working on and discussing improvements with the help of [pull requests](https://github.com/JabRef/jabref/pulls). One can see the binaries of each branch at [https://builds.jabref.org/](https://builds.jabref.org). Releases mark milestones and are based on the `main` branch at that point in time.
 
-Without jlink, it is not possible to generate a fat jar any more. During development, the capabilities of the IDE has to be used.
+## How JabRef acquires contributors
 
-### Groups
+* We participate in [Hacktoberfest](https://www.hacktoberfest.com).
+* We participate in [Google Summer of Code](https://developers.google.com/open-source/gsoc/).
+* We are very happy that JabRef is part of [Software Engineering](https://en.wikipedia.org/wiki/Software_engineering) trainings.
+  Please head to [Teaching](teaching.md) for more information on using JabRef as a teaching object and on previous courses where JabRef was used.
 
-Diagram showing aspects of groups: [Groups.uml](https://github.com/JabRef/jabref/tree/3b3716b1e05a0d3273c886e102a8efe5e96472e0/docs/Groups.uml).
+## High-level architecture
 
-## Architectural Decision Records
+In JabRef's code structure,
 
-[Architectural decisions for JabRef](https://devdocs.jabref.org/decisions/) are recorded.
+The `model` package encompasses the most important data structures (`BibDatases`, `BibEntries`, `Events`, and related aspects) and has minimal logic attached.
+The `logic` package is responsible for business logic such as reading/writing/importing/exporting and manipulating the `model`, and it is structured often as an API the `gui` can call and use.
+Only the `gui` knows the user and their preferences and can interact with them to help them solving tasks.
+For each layer, we form packages according to their responsibility, i.e., vertical structuring.
+The `model` classes should have no dependencies to other classes of JabRef and the `logic` classes should only depend on `model` classes.
+The `cli` package bundles classes that are responsible for JabRef's command line interface.
+The `preferences` package represents all information customizable by a user for their personal needs.
 
-For new ADRs, please use [adr-template.md](https://github.com/JabRef/jabref/blob/main/docs/decisions/adr-template.md) as basis.
-More information on MADR is available at <https://adr.github.io/madr/>.
-General information about architectural decision records is available at <https://adr.github.io/>.
+We use an event bus to publish events from the `model` to the other layers.
+This allows us to keep the architecture but still react upon changes within the core in the outer layers.
+Note that we are currently switching to JavaFX's observables, as we aim for a stronger coupling to the data producers.
+
+### Package Structure
+
+Permitted dependencies in our architecture are:
+
+```monospaced
+gui --> logic --> model
+gui ------------> model
+gui ------------> preferences
+gui ------------> cli
+gui ------------> global classes
+
+logic ------------> model
 
-## FAQ
+global classes ------------> everywhere
 
-* Q: I get `java: package org.jabref.logic.journals does not exist`.
+cli ------------> model
+cli ------------> logic
+cli ------------> global classes
+cli ------------> preferences
+```
 
-  A: You have to ignore `buildSrc/src/main` as source directory in IntelliJ as indicated in our [setup guide](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace).
+All packages and classes which are currently not part of these packages (we are still in the process of structuring) are considered as gui classes from a dependency standpoint.
 
-  Also filed as IntelliJ issue [IDEA-240250](https://youtrack.jetbrains.com/issue/IDEA-240250).
+### Most Important Classes and their Relation
+
+Both GUI and CLI are started via the `JabRefMain` which, in turn, calls `JabRef` which then decides whether the GUI (`JabRefFrame`) or the CLI (`JabRefCLI` and a lot of code in `JabRef`) will be started. The `JabRefFrame` represents the Window which contains a `SidePane` on the left used for the fetchers/groups. Each tab is a `BasePanel` which has a `SearchBar` at the top, a `MainTable` at the center and a `PreviewPanel` or an `EntryEditor` at the bottom. Any right click on the `MainTable` is handled by the `RightClickMenu`. Each `BasePanel` holds a `BibDatabaseContext` consisting of a `BibDatabase` and the `MetaData` (which is relevant data of the currently focussed database). A `BibDatabase` has a list of `BibEntries`. Each `BibEntry` has an ID, a citation key and a key/value store for the fields with their values. Interpreted data (such as the type or the file field) is stored in the `TypedBibentry` type. The user can change the `JabRefPreferences` through the `PreferencesDialog`.
+
+## Architectural Decision Records
+
+JabRef collects core architecture decisions using "Architectural Decision Records".
+They are available at <https://devdocs.jabref.org/decisions/>.
+
+For new ADRs, please use [adr-template.md](https://github.com/JabRef/jabref/blob/main/docs/decisions/adr-template.md) as basis.
+More information on MADR is available at <https://adr.github.io/madr/>.
+General information about architectural decision records is available at <https://adr.github.io/>.
