feat(git): add “Share to GitHub” flow

docs/decisions/0016-mutable-preferences-objects.md

@@ -18,3 +18,9 @@ To create an immutable preferences object every time seems to be a waste of time
 Chosen option: "Alter the exiting object", because the preferences objects are just wrappers around the basic preferences framework of JDK. They
 should be mutable on-the-fly similar to objects with a Builder inside and to be stored immediately again in the
 preferences.
+
+### Consequences
+
+* Import logic will be more hard as exising preferences objects have to be altered; and it is very hard to know which preference objects exactly are needed to be modified.
+* Cached variables need to be observables, too. AKA The cache needs to be observable.
+* There is NO "real" factory pattern for the preferences objects, as they are mutable --> they are passed via the constructor and long-lived

jabgui/src/main/java/org/jabref/gui/actions/StandardActions.java

@@ -217,7 +217,13 @@ public enum StandardActions implements Action {
     GROUP_SUBGROUP_RENAME(Localization.lang("Rename subgroup"), KeyBinding.GROUP_SUBGROUP_RENAME),
     GROUP_ENTRIES_REMOVE(Localization.lang("Remove selected entries from this group")),
 
-    CLEAR_EMBEDDINGS_CACHE(Localization.lang("Clear embeddings cache"));
+    CLEAR_EMBEDDINGS_CACHE(Localization.lang("Clear embeddings cache")),
+
+    GIT(Localization.lang("Git"), IconTheme.JabRefIcons.GIT_SYNC),
+    GIT_PULL(Localization.lang("Pull")),
+    GIT_PUSH(Localization.lang("Push")),
+    GIT_COMMIT(Localization.lang("Commit")),
+    GIT_SHARE(Localization.lang("Share this library to GitHub"));
 
     private String text;
     private final String description;

jabgui/src/main/java/org/jabref/gui/frame/MainMenu.java

@@ -39,6 +39,7 @@
 import org.jabref.gui.externalfiles.AutoLinkFilesAction;
 import org.jabref.gui.externalfiles.DownloadFullTextAction;
 import org.jabref.gui.externalfiles.FindUnlinkedFilesAction;
+import org.jabref.gui.git.GitShareToGitHubAction;
 import org.jabref.gui.help.AboutAction;
 import org.jabref.gui.help.ErrorConsoleAction;
 import org.jabref.gui.help.HelpAction;
@@ -180,10 +181,19 @@ private void createMenu() {
 
                 new SeparatorMenuItem(),
 
+                // region: Sharing of the library
+
+                // TODO: Should be only enabled if not yet shared.
+                factory.createSubMenu(StandardActions.GIT,
+                        factory.createMenuItem(StandardActions.GIT_SHARE, new GitShareToGitHubAction(dialogService, stateManager))
+                ),
+
                 factory.createSubMenu(StandardActions.REMOTE_DB,
                         factory.createMenuItem(StandardActions.CONNECT_TO_SHARED_DB, new ConnectToSharedDatabaseCommand(frame, dialogService)),
                         factory.createMenuItem(StandardActions.PULL_CHANGES_FROM_SHARED_DB, new PullChangesFromSharedAction(stateManager))),
 
+                // endregion
+
                 new SeparatorMenuItem(),
 
                 factory.createMenuItem(StandardActions.SHOW_PREFS, new ShowPreferencesAction(frame, dialogService)),

jabgui/src/main/java/org/jabref/gui/git/GitPullViewModel.java

@@ -25,12 +25,12 @@ public GitPullViewModel(GitSyncService syncService, GitStatusViewModel gitStatus
     public MergeResult pull() throws IOException, GitAPIException, JabRefException {
         Optional<BibDatabaseContext> databaseContextOpt = gitStatusViewModel.getDatabaseContext();
         if (databaseContextOpt.isEmpty()) {
-            throw new JabRefException(Localization.lang("Cannot pull: No active BibDatabaseContext."));
+            throw new JabRefException(Localization.lang("No library selected"));
         }
 
         BibDatabaseContext localBibDatabaseContext = databaseContextOpt.get();
         Path bibFilePath = localBibDatabaseContext.getDatabasePath().orElseThrow(() ->
-                new JabRefException(Localization.lang("Cannot pull: .bib file path missing in BibDatabaseContext."))
+                new JabRefException(Localization.lang("Cannot pull: Please save the library to a file first."))
         );
 
         MergeResult result = syncService.fetchAndMerge(localBibDatabaseContext, bibFilePath);

jabgui/src/main/java/org/jabref/gui/git/GitShareToGitHubAction.java

@@ -0,0 +1,38 @@
+package org.jabref.gui.git;
+
+import javafx.beans.binding.BooleanExpression;
+
+import org.jabref.gui.DialogService;
+import org.jabref.gui.StateManager;
+import org.jabref.gui.actions.SimpleCommand;
+
+import static org.jabref.gui.actions.ActionHelper.needsDatabase;
+
+public class GitShareToGitHubAction extends SimpleCommand {
+    private final DialogService dialogService;
+    private final StateManager stateManager;
+
+    public GitShareToGitHubAction(
+            DialogService dialogService,
+            StateManager stateManager) {
+        this.dialogService = dialogService;
+        this.stateManager = stateManager;
+
+        this.executable.bind(this.enabledGitShare());
+    }
+
+    @Override
+    public void execute() {
+        dialogService.showCustomDialogAndWait(new GitShareToGitHubDialogView());
+    }
+
+    private BooleanExpression enabledGitShare() {
+        // TODO: Determine the correct condition for enabling "Git Share". This currently only requires an open library.
+        //  In the future, this may need to check whether:
+        //  - the repo is initialized (because without a repository, the current implementation does not work -> future work)
+        //  - etc.
+        // Can be called independent if a remote is configured or not -- it will be done in the dialog
+        // HowTo: Inject the observables (or maybe the stateManager) containing these constraints
+        return needsDatabase(stateManager);
+    }
+}

jabgui/src/main/java/org/jabref/gui/git/GitShareToGitHubDialogView.java

@@ -0,0 +1,129 @@
+package org.jabref.gui.git;
+
+import javafx.application.Platform;
+import javafx.fxml.FXML;
+import javafx.scene.control.ButtonType;
+import javafx.scene.control.CheckBox;
+import javafx.scene.control.Label;
+import javafx.scene.control.PasswordField;
+import javafx.scene.control.TextField;
+import javafx.scene.control.Tooltip;
+
+import org.jabref.gui.DialogService;
+import org.jabref.gui.StateManager;
+import org.jabref.gui.desktop.os.NativeDesktop;
+import org.jabref.gui.preferences.GuiPreferences;
+import org.jabref.gui.util.BaseDialog;
+import org.jabref.gui.util.IconValidationDecorator;
+import org.jabref.logic.l10n.Localization;
+import org.jabref.logic.util.TaskExecutor;
+
+import com.airhacks.afterburner.views.ViewLoader;
+import de.saxsys.mvvmfx.utils.validation.visualization.ControlsFxVisualizer;
+import jakarta.inject.Inject;
+
+public class GitShareToGitHubDialogView extends BaseDialog<Void> {
+    private static final String GITHUB_PAT_DOCS_URL =
+            "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens";
+
+    private static final String GITHUB_NEW_REPO_URL = "https://github.com/new";
+
+    @FXML private TextField repositoryUrl;
+    @FXML private TextField username;
+    @FXML private PasswordField personalAccessToken;
+    @FXML private ButtonType shareButton;
+    @FXML private Label patHelpIcon;
+    @FXML private Tooltip patHelpTooltip;
+    @FXML private CheckBox rememberSettingsCheck;
+    @FXML private Label repoHelpIcon;
+    @FXML private Tooltip repoHelpTooltip;
+
+    private GitShareToGitHubDialogViewModel viewModel;
+
+    @Inject
+    private DialogService dialogService;
+
+    @Inject
+    private StateManager stateManager;
+
+    @Inject
+    private TaskExecutor taskExecutor;
+
+    @Inject
+    private GuiPreferences preferences;
+
+    private final ControlsFxVisualizer visualizer = new ControlsFxVisualizer();
+
+    public GitShareToGitHubDialogView() {
+        ViewLoader.view(this)
+                  .load()
+                  .setAsDialogPane(this);
+    }
+
+    @FXML
+    private void initialize() {
+        this.viewModel = new GitShareToGitHubDialogViewModel(preferences.getGitPreferences(), stateManager, dialogService, taskExecutor);
+
+        this.setTitle(Localization.lang("Share this Library to GitHub"));
+
+        // See "javafx.md"
+        this.setResultConverter(button -> {
+            if (button != ButtonType.CANCEL) {
+                // We do not want to use "OK", but we want to use a custom text instead.
+                // JavaFX does not allow to alter the text of the "OK" button.
+                // Therefore, we used another button type.
+                // Since we have only two buttons, we can check for non-cancel here.
+                shareToGitHub();
+            }
+            return null;
+        });
+
+        patHelpTooltip.setText(
+                Localization.lang("Click to open GitHub Personal Access Token documentation")
+        );
+
+        username.setPromptText(Localization.lang("Your GitHub username"));
+        personalAccessToken.setPromptText(Localization.lang("PAT with repo access"));
+
+        repoHelpTooltip.setText(
+                Localization.lang("Create an empty repository on GitHub, then copy the HTTPS URL (ends with .git). Click to open GitHub.")
+        );
+        Tooltip.install(repoHelpIcon, repoHelpTooltip);
+        repoHelpIcon.setOnMouseClicked(e ->
+                NativeDesktop.openBrowserShowPopup(
+                        GITHUB_NEW_REPO_URL,
+                        dialogService,
+                        preferences.getExternalApplicationsPreferences()
+                )
+        );
+
+        Tooltip.install(patHelpIcon, patHelpTooltip);
+        patHelpIcon.setOnMouseClicked(e ->
+                NativeDesktop.openBrowserShowPopup(
+                        GITHUB_PAT_DOCS_URL,
+                        dialogService,
+                        preferences.getExternalApplicationsPreferences()
+                )
+        );
+
+        repositoryUrl.textProperty().bindBidirectional(viewModel.repositoryUrlProperty());
+        username.textProperty().bindBidirectional(viewModel.usernameProperty());
+        personalAccessToken.textProperty().bindBidirectional(viewModel.patProperty());
+        rememberSettingsCheck.selectedProperty().bindBidirectional(viewModel.rememberPatProperty());
+
+        viewModel.setValues();
+
+        Platform.runLater(() -> {
+            visualizer.setDecoration(new IconValidationDecorator());
+
+            visualizer.initVisualization(viewModel.repositoryUrlValidation(), repositoryUrl, true);
+            visualizer.initVisualization(viewModel.githubUsernameValidation(), username, true);
+            visualizer.initVisualization(viewModel.githubPatValidation(), personalAccessToken, true);
+        });
+    }
+
+    @FXML
+    private void shareToGitHub() {
+        viewModel.shareToGitHub(() -> this.close());
+    }
+}