docs: start writing upgrade guide

.editorconfig

@@ -1,26 +1,9 @@
 # -*- coding: utf-8 -*-
-#
 # This file is part of Invenio.
-# Copyright (C) 2016 CERN.
-#
-# Invenio is free software; you can redistribute it
-# and/or modify it under the terms of the GNU General Public License as
-# published by the Free Software Foundation; either version 2 of the
-# License, or (at your option) any later version.
-#
-# Invenio is distributed in the hope that it will be
-# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Invenio; if not, write to the
-# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-# MA 02111-1307, USA.
+# Copyright (C) 2025 CERN.
 #
-# In applying this license, CERN does not
-# waive the privileges and immunities granted to it by virtue of its status
-# as an Intergovernmental Organization or submit itself to any jurisdiction.
+# Invenio is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
 
 
 root = true

.travis.yml

@@ -1,26 +1,9 @@
 # -*- coding: utf-8 -*-
-#
 # This file is part of Invenio.
-# Copyright (C) 2016 CERN.
-#
-# Invenio is free software; you can redistribute it
-# and/or modify it under the terms of the GNU General Public License as
-# published by the Free Software Foundation; either version 2 of the
-# License, or (at your option) any later version.
-#
-# Invenio is distributed in the hope that it will be
-# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Invenio; if not, write to the
-# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-# MA 02111-1307, USA.
+# Copyright (C) 2025 CERN.
 #
-# In applying this license, CERN does not
-# waive the privileges and immunities granted to it by virtue of its status
-# as an Intergovernmental Organization or submit itself to any jurisdiction.
+# Invenio is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
 
 
 notifications:

AUTHORS.rst

@@ -1,26 +1,9 @@
 ..
     This file is part of Invenio.
-    Copyright (C) 2016 CERN.
-
-    Invenio is free software; you can redistribute it
-    and/or modify it under the terms of the GNU General Public License as
-    published by the Free Software Foundation; either version 2 of the
-    License, or (at your option) any later version.
-
-    Invenio is distributed in the hope that it will be
-    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-    General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with Invenio; if not, write to the
-    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-    MA 02111-1307, USA.
-
-    In applying this license, CERN does not
-    waive the privileges and immunities granted to it by virtue of its status
-    as an Intergovernmental Organization or submit itself to any jurisdiction.
+    Copyright (C) 2025 CERN.
 
+    Invenio is free software; you can redistribute it and/or modify it
+    under the terms of the MIT License; see LICENSE file for more details.
 
 Authors
 =======

CHANGES.rst

@@ -1,27 +1,10 @@
 ..
     This file is part of Invenio.
-    Copyright (C) 2016-2024 CERN.
+    Copyright (C) 2016-2025 CERN.
     Copyright (C) 2024-2025 Graz University of Technology.
 
-    Invenio is free software; you can redistribute it
-    and/or modify it under the terms of the GNU General Public License as
-    published by the Free Software Foundation; either version 2 of the
-    License, or (at your option) any later version.
-
-    Invenio is distributed in the hope that it will be
-    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-    General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with Invenio; if not, write to the
-    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-    MA 02111-1307, USA.
-
-    In applying this license, CERN does not
-    waive the privileges and immunities granted to it by virtue of its status
-    as an Intergovernmental Organization or submit itself to any jurisdiction.
-
+    Invenio is free software; you can redistribute it and/or modify it
+    under the terms of the MIT License; see LICENSE file for more details.
 
 Changes
 =======

MANIFEST.in

@@ -1,26 +1,9 @@
 # -*- coding: utf-8 -*-
-#
 # This file is part of Invenio.
-# Copyright (C) 2023 CERN.
-#
-# Invenio is free software; you can redistribute it
-# and/or modify it under the terms of the GNU General Public License as
-# published by the Free Software Foundation; either version 2 of the
-# License, or (at your option) any later version.
-#
-# Invenio is distributed in the hope that it will be
-# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Invenio; if not, write to the
-# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-# MA 02111-1307, USA.
+# Copyright (C) 2025 CERN.
 #
-# In applying this license, CERN does not
-# waive the privileges and immunities granted to it by virtue of its status
-# as an Intergovernmental Organization or submit itself to any jurisdiction.
+# Invenio is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
 
 
 exclude .dockerignore

README.rst

@@ -1,25 +1,9 @@
 ..
     This file is part of Invenio.
-    Copyright (C) 2023 CERN.
-
-    Invenio is free software; you can redistribute it
-    and/or modify it under the terms of the GNU General Public License as
-    published by the Free Software Foundation; either version 2 of the
-    License, or (at your option) any later version.
-
-    Invenio is distributed in the hope that it will be
-    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-    General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with Invenio; if not, write to the
-    Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-    MA 02111-1307, USA.
-
-    In applying this license, CERN does not
-    waive the privileges and immunities granted to it by virtue of its status
-    as an Intergovernmental Organization or submit itself to any jurisdiction.
+    Copyright (C) 2025 CERN.
+
+    Invenio is free software; you can redistribute it and/or modify it
+    under the terms of the MIT License; see LICENSE file for more details.
 
 ================
  Invenio-GitHub

docs/api.rst

@@ -25,6 +25,5 @@
 API Docs
 ========
 
-invenio_github
---------------
-
+.. automodule:: invenio_vcs.ext
+   :members:

docs/conf.py

@@ -1,27 +1,9 @@
 # -*- coding: utf-8 -*-
-#
 # This file is part of Invenio.
-# Copyright (C) 2016 CERN.
-# Copyright (C) 2023 Graz University of Technology.
-#
-# Invenio is free software; you can redistribute it
-# and/or modify it under the terms of the GNU General Public License as
-# published by the Free Software Foundation; either version 2 of the
-# License, or (at your option) any later version.
-#
-# Invenio is distributed in the hope that it will be
-# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Invenio; if not, write to the
-# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-# MA 02111-1307, USA.
+# Copyright (C) 2025 CERN.
 #
-# In applying this license, CERN does not
-# waive the privileges and immunities granted to it by virtue of its status
-# as an Intergovernmental Organization or submit itself to any jurisdiction.
+# Invenio is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
 
 """Sphinx configuration."""
 

docs/contrib/github.rst

@@ -0,0 +1,41 @@
+..
+    This file is part of Invenio.
+    Copyright (C) 2025 CERN.
+
+    Invenio is free software; you can redistribute it and/or modify it
+    under the terms of the MIT License; see LICENSE file for more details.
+
+GitHub
+======
+
+To register GitHub as a VCS provider:
+
+* instantiate ``invenio_vcs.contrib.github.GitHubProviderFactory``
+* add it into the ``VCS_PROVIDERS`` list
+* add it into the ``OAUTHCLIENT_REMOTE_APPS`` and ``OAUTHCLIENT_REST_REMOTE_APPS`` dictionaries under the same key as the ID (``github`` by default).
+* configure ``GITHUB_APP_CREDENTIALS`` with your OAuth credentials generated by GitHub.
+
+For more details and a full example, please see `the Usage Guide <../usage>`_.
+
+==================
+OAuth registration
+==================
+
+To register a GitHub VCS provider, you need to `create an OAuth app <https://github.com/settings/applications/new>`_ in your Developer Settings.
+
+You can enter any details for the app, but the authorization callback URL must be of the form:
+
+.. code-block::
+
+  https://example.com/oauth/authorized/github/
+
+where ``example.com`` is the hostname of your instance and ``github`` is your configured provider ID.
+
+=====================
+Special config values
+=====================
+
+These optional values can be passed as keys of the ``config`` dictionary in the ``GitHubProviderFactory`` constructor.
+
+* ``shared_secret``: signing secret for the webhook payload. See the `GitHub documentation <https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries>`_ for more details. Currently, one instance-wide secret is used for all webhooks. In addition, an internal per-repository access token is automatically attached to the webhook URL to validate access.
+* ``insecure_ssl``: a boolean to indicate whether GitHub should accept self-signed or otherwise insecure SSl/TLS certificates when attempting to deliver the webhook.

docs/contrib/gitlab.rst

@@ -0,0 +1,63 @@
+..
+    This file is part of Invenio.
+    Copyright (C) 2025 CERN.
+
+    Invenio is free software; you can redistribute it and/or modify it
+    under the terms of the MIT License; see LICENSE file for more details.
+
+GitLab
+======
+
+To register GitLab as a VCS provider:
+
+* instantiate ``invenio_vcs.contrib.gitlab.GitLabProviderFactory``
+* add it into the ``VCS_PROVIDERS`` list
+* add it into the ``OAUTHCLIENT_REMOTE_APPS`` and ``OAUTHCLIENT_REST_REMOTE_APPS`` dictionaries under the same key as the ID (``gitlab`` by default).
+* configure ``GITLAB_APP_CREDENTIALS`` with your OAuth credentials generated by GitLab.
+
+For more details and a full example, please see `the Usage Guide <../usage>`_.
+
+=============
+Compatibility
+=============
+
+The integration has been tested to work with the following versions of GitLab:
+
+* 18.x
+* 17.x
+* 16.x
+
+Support for anything but the latest major version is not guaranteed.
+Please refer also to the `GitLab release policy <https://docs.gitlab.com/policy/maintenance/#maintained-versions>`_.
+
+Any modified GitLab instances running custom code are also not guaranteed to be compatible.
+You can, however, override the ``invenio_vcs.contrib.gitlab.GitLabProviderFactory`` and ``invenio_vcs.contrib.gitlab.GitLabProvider`` classes to add support for any non-standard API behaviour.
+
+==================
+OAuth registration
+==================
+
+To register a GitLab VCS provider, you need to `create a new Application <https://gitlab.com/-/user_settings/applications>`_ in your User Settings.
+For a self-hosted GitLab instance, navigate to ``https://my-gitlab-instance.com/-/user_settings/applications``.
+
+Configure the app with the following settings:
+
+* You can use any name.
+* Use a redirect URI of the form
+
+  .. code-block::
+
+    https://example.com/oauth/authorized/gitlab/
+
+  where ``example.com`` is the hostname of your instance and ``gitlab`` is your configured provider ID.
+
+* Ensure 'Confidential' is checked.
+* Select the ``api`` scope. Unfortunately, webhook management doesn't currently have a more narrow scope so this highly-general scope must be selected.
+
+=====================
+Special config values
+=====================
+
+These optional values can be passed as keys of the ``config`` dictionary in the ``GitHubProviderFactory`` constructor.
+
+* ``shared_validation_token``: Validation secret token for the webhook payload. See the `GitLab documentation <https://docs.gitlab.com/user/project/integrations/webhooks/#create-a-webhook>`_ for more details. Currently, one instance-wide token is used for all webhooks. In addition, an internal per-repository access token is automatically attached to the webhook URL to validate access.

docs/index.rst

@@ -37,6 +37,30 @@ Invenio-GitHub.
    usage
 
 
+Provider Guides
+---------------
+
+These docs provide configuration instructions specific to each VCS provider.
+
+.. toctree::
+
+    contrib/github
+    contrib/gitlab
+
+
+
+Provider Guides
+---------------
+
+These docs provide configuration instructions specific to each VCS provider.
+
+.. toctree::
+
+    contrib/github
+    contrib/gitlab
+
+
+
 API Reference
 -------------