merged main

docs/contributing/releasing-islandora.md

@@ -9,7 +9,7 @@ Islandora is an ecosystem of repositories and follows a [Semantic Versioning App
 
 [Learn more about Islandora's Versioning Policy](https://islandora.github.io/documentation/technical-documentation/versioning/)
 
-
+**Note to module maintainers specifying composer requirements:** please familiarize yourself with the [Next Significant Release Modifiers](https://getcomposer.org/doc/articles/versions.md#next-significant-release-operators)  so that module dependencies are as permissive as possible. Most often dependency versions should be tagged using the caret (^) so that bug-fixes and minor releases can be pulled in without updating their module’s composer file.
 
 ### How to Release Java Code
 
@@ -113,19 +113,20 @@ completed all the above steps and are absolutely certain the release is ready fo
 
 ### JSONLD
 
-Release the `jsonld` module by creating a new release for it in Github.
+Release the `jsonld` module by creating a new release for it in Github and on Drupal.org.
 
 ### Release OpenSeadragon
 
-Release the `openseadragon` module by creating a new release for it in Github.
+Release the `openseadragon` module by creating a new release for it in Github and on Drupal.org.
 
 ### Release Islandora Mirador
 
-Release the `islandora_mirador` module by creating a new release for it in Github.
+Release the `islandora_mirador` module by creating a new release for it in Github and on Drupal.org.
 
 ### Release migrate_islandora_csv
 
-Release the `migrate_islandora_csv` module by creating a new release for it in Github.
+Release the `migrate_islandora_csv` module by creating a new release for it in Github. This module 
+is minimally maintained on Drupal.org and if you are updating it, consider editing that.
 
 ### Release Chullo
 
@@ -157,21 +158,12 @@ Crayfish depends on the `crayfish-commons` library, and must have its dependenci
 
 ### Release Controlled Access Terms
 
-Release controlled_access_terms by slicing a new release for it in Github.
+Release controlled_access_terms by creating a new release for it in Github and on Drupal.org.
 
 ### Release Islandora
 
-The `islandora` module depends on the `crayfish-commons` library, and must have its dependencies updated before release.
-
-1. Bump the dependency on `islandora/crayfish-commons` in `composer.json`.
-2. Run `composer update -W`
-4. Commit and push the `composer.json` and `composer.lock` files to Github.
-5. Release the module by creating a new release for them in Github.
-6. Put the dependencies on `islandora/crayfish-commons` back to `dev-dev`
-7. Run `composer update -W` again.
-8. Commit and push the `composer.json` and `composer.lock` files to Github with a commit message of "Preparing for next development iteration".
+Release islandora by creating a new release for it in Github and on Drupal.org.
 
-**Note to module maintainers specifying composer requirements:** please familiarize yourself with the [Next Significant Release Modifiers](https://getcomposer.org/doc/articles/versions.md#next-significant-release-operators)  so that module dependencies are as permissive as possible. Most often dependency versions should be tagged using the caret (^) so that bug-fixes and minor releases can be pulled in without updating their module’s composer file.
 
 ## Undoing a Release
 

docs/contributing/testing-a-pull-request.md

@@ -0,0 +1,239 @@
+# Testing a Pull Request (i.e. Running Custom Code)
+
+If you are testing a pull request, or for other reasons need to replace the
+"official" code with code that's in a PR, or a different branch or fork, this
+page offers three methods: using Composer Patches, using Composer to
+require the branch and/or fork or installing source repositories with Composer.
+
+This documentation applies to Drupal modules, themes, and recipes, or any
+other project that is managed by Composer.
+
+!!! note "Can't I just `git clone`?"
+    When managing a non-developmental site with Composer, it's very fragile to
+    use commands like `git clone` to obtain code, as it can be overwritten by
+    a `composer update`.
+
+    For those who are comfortable cloning code onto a development environment, refer to
+    [Installing Git repositories with Composer](#installing-git-repositories-with-composer).
+
+## Applying a Patch using Composer Patches
+
+This method is best for testing pull requests, because it's very easy to get a
+patch from a pull request. If the desired code is not the subject of a
+PR, you can still use this method but must generate a `.patch` file yourself.
+You may wish to use the [fork or branch](#using-composer-to-require-a-fork-or-branch)
+method, as it is more dynamic.
+
+Run the following commands from within your site's root folder. They will
+update your `composer.json` file.
+
+```shell
+# Enable Composer Patches
+composer config allow-plugins.cweagans/composer-patches true
+composer require cweagans/composer-patches
+```
+
+For the next step, prepare the following replacement tokens:
+
+* `MY_PACKAGE`: The full Composer name of the package to patch. It
+  takes the form [vendor name]/[project name]. Example:
+  `drupal/controlled_access_terms`
+* `MY_ISSUE_TITLE`: A descriptive way to identify what the patch is for.
+  Best practice is to include a link to the related issue -
+  especially if you're going to keep this patch around for a while.
+  Example: `Updated config format https://github.com/Islandora/controlled_access_terms/issues/117`
+* `MY_PATCH_LOCATION`: Where to access the patch. See below.
+
+To get the URL of a patch for a PR, go to the PR's main URL, and append
+`.patch` to the URL. Make sure that your URL ends with `pull/XX.patch`
+and not `pull/XX/files.patch` - the latter will not work.
+
+If you don't have a PR, you could create a patch using `diff`. However, this
+patch will be static and will need to be updated manually if your code
+changes. You can put patches in a folder in your root directory such as `
+[COMPOSER_ROOT]/assets/` and then the patch location would be
+`assets/my_patch_name.patch`.
+
+This one-liner, with the substitutions above, will add the patch to your
+`composer.json`:
+
+```shell
+# Add patch to composer.json
+composer config extra.patches --merge --json '{"MY_PACKAGE": {"MY_ISSUE_TITLE": "MY_PATCH_LOCATION"}}'
+
+```
+
+Or you could manually edit `composer.json` so it contains the following
+(`...` denotes omitted content):
+```json
+{
+  ...
+  extra: {
+    ...   
+    patches: {
+      "MY_PACKAGE": {
+        "MY_ISSUE_TITLE": "MY_PATCH_LOCATION"
+      }
+    }
+  }
+}
+```
+
+Then, update your package (recall e.g. `drupal/controlled_access_terms`)
+using Composer:
+
+```shell
+composer update MY_PACKAGE
+```
+
+The patch should apply, and then you will be running a patched version! If
+you're using a dynamic patch, then running `composer update` again should
+pull in changes to the code.
+
+## Using Composer to require a fork or branch
+
+This method is best if you don't have a pull request open for the code.
+
+### Step 1: Add a repository (if necessary)
+
+If your code is on a fork, then you will need to add a repository to
+Composer so that it knows where to get your package.
+
+If the code that you want to test is a different branch/tag on the same
+repository that you're currently getting your code from, then you do not
+need to add a repository.
+
+Prepare the following replacement tokens before adding a repository:
+
+* `REPO_NAME`: a name for this repository (mandatory if using the composer
+  one-liner), e.g. `rosiel-islandora`
+* `REPO_URL`: the URL to the repository, e.g. `https://github.com/rosiel/islandora`
+
+```shell
+# Add custom repo
+composer config repo.REPO_NAME vcs REPO_URL
+```
+Your `composer.json` file should now contain
+
+```json
+{
+  ...
+  "repositories": {
+    ...
+    "REPO_NAME": {
+      "type": "vcs",
+      "url": "REPO_URL"
+    }
+  }
+}
+```
+
+!!! note "Order of precedence of repositories"
+    If you have a matching version spec (e.g. branch name) that's available
+    from multiple repositories, e.g. both islandora's Gitlab and your personal
+    fork both have an `enable-hocr` branch, then the repository that's first
+    in the list in composer.json will take precedence.
+
+### Step 2: Require the custom branch
+
+This step could be as simple as
+```shell
+composer require MY_PACKAGE:dev-MY_BRANCH_NAME
+```
+
+with the following replacements:
+
+* `MY_PACKAGE`: the full Composer name of the package. Example:
+`drupal/islandora`
+* `MY_BRANCH_NAME`: the name of the branch you want to run. Example:
+  `testing-fedora-6`. Note that in the case that your branch name is
+  "version-like" for example `2.x`, then the `dev` goes at the end, as in
+  `2.x-dev`, instead of preceding the branch name as in the template above.
+
+
+However, if your component is a dependency of another component, then you
+will probably need to use an alias. This allows your custom code to "act as"
+a version that will meet the requirements of your other component. For
+example, if the `drupal/islandora_mirador` package requires
+`drupal/islandora:^2.4.1`, then using Composer to require the `enable-hocr`
+branch of `drupal/islandora` will not meet the requirements. Instead, use
+`as` to provide an alias, to a version that will match the constraints. Note
+the quotes around the package name and version spec. This takes the form:
+
+```shell
+composer require "MY_PACKAGE:dev-MY_BRANCH_NAME as ALIAS"
+```
+For example:
+```shell
+composer require "drupal/islandora:dev-enable-hocr as 2.12.1"
+```
+
+That will install the specified branch and allow it to work with your
+dependencies.
+
+## Installing Git repositories with Composer
+
+This method pulls the source (i.e. Git) repositories directly into your project
+and will allow you to pull in open pull requests by simply following a normal
+Git workflow.
+
+!!!note
+    If the site has already been installed without using `--prefer-source` you
+    will need to clear Composer's cache via `composer clearcache` or including
+    `--no-cache` for any `install` or `reinstall` commands (as below).
+
+### Step 1: Re-install the code from source (if required)
+Assuming that the environment has not been installed with `--prefer-source`,
+reinstall the package.
+
+```shell
+composer reinstall MY_PACKAGE --prefer-source
+```
+with the following replacements:
+
+* `MY_PACKAGE`: the full Composer name of the package. Example:
+  `drupal/islandora`
+
+This will pull the code from the source repository (i.e. including the `.git`
+files) and add the package code at the same version of the `MY_PACKAGE`
+that was previously installed and is in the lock file.
+
+For example:
+```shell
+composer reinstall "drupal/islandora" --prefer-source --no-cache
+```
+
+### Step 2: Pull the code from the pull request to review.
+Follow Github's [documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally)
+to pull the code from the pull request to review.
+
+Now you can test your specified code, as well as edit the code and create
+commits. Note that if you're doing this in a throwaway environment such as a VM
+or a Docker Container, you will need to configure authentication (e.g.
+install an SSH key with Github) before you can push your commits.
+
+## To reset these changes
+
+### ... using Composer Patches
+
+When you no longer need to be applying the patch, simply remove it from the
+`patches:` section of `composer.json` (and of course, take care to ensure the
+json remains valid, by adjusting commas!) and run `composer update MY_PACKAGE`.
+
+### ... using Composer require
+
+When you no longer want to pull from a separate branch or fork, reset the
+version constraint back to what it used to be, or, if your package was not
+originally in `composer.json` (because it is required as a dependency by
+another package), you can delete the requirement from your `composer.json`.
+Then run `composer update MY_PACKAGE`. If you added a repository, it's
+safest to delete the repository, as it could lead to you getting stale
+branches from a fork rather than the desired active code from the canonical
+repository.
+
+### ... using source repositories
+
+When you no longer want the custom code present simply reset the branch back to
+the default branch or tag.
+
+More great information is available in the [Composer Documentation](https://getcomposer.org/doc/).

docs/installation/playbook.md

@@ -1,6 +1,6 @@
 # Islandora Playbook
 
-The Islandora Playbook ([Islandora-Devops/islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook)) is a tool for installing the Islandora stack on a single virtual machine. It can be used both as a [Vagrant](https://www.vagrantup.com/) project to create a local development environment, or as an [Ansible](https://www.ansible.com/community) playbook to provision a local or remote server. It can set up a Drupal based either on Islandora Starter Site, or on the Install Profile Demo.
+The Islandora Playbook ([Islandora-Devops/islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook)) is a tool for installing the Islandora stack on a single virtual machine. It can be used both as a [Vagrant](https://www.vagrantup.com/) project to create a local development environment, or as an [Ansible](https://www.ansible.com/community) playbook to provision a local or remote server. It can set up a Drupal based either on Islandora Starter Site, or your own custom site configs.
 
 ## Basic Usage (Vagrant):
 

docs/technical-documentation/install-enable-drupal-modules.md

@@ -2,12 +2,12 @@
 
 Islandora can make use of the majority of Drupal [modules](https://www.drupal.org/project/project_module) and [themes](https://www.drupal.org/project/project_theme). Common use cases have been documented in the [Islandora Cookbook](/documentation/user-documentation/extending/). There are several ways to download and install Drupal modules. Please refer to [this guide](https://www.drupal.org/docs/extending-drupal) on Drupal.org.
 
-[Composer](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) is the recommended method to install and update drupal modules and themes in Islandora.
+[Composer](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) is the recommended method to install and update drupal modules and themes in Islandora. Drupal modules provided by Islandora can be accessed at the `drupal/` namespace.
 ```shell
 $ composer require "<vendor>/<package>:<version>"
 
 # Example
-$ composer require "islandora/jsonld:^2"
+$ composer require "drupal/jsonld:^2"
 ```
 
 In the [Islandora playbook](https://github.com/Islandora-Devops/islandora-playbook), you can add a Drupal module's or theme's machine name to the `drupal_composer_dependencies` variable [here](https://github.com/Islandora-Devops/islandora-playbook/blob/dev/inventory/vagrant/group_vars/webserver/drupal.yml).

docs/technical-documentation/versioning.md

@@ -26,7 +26,7 @@ The following Islandora components use semantic versioning:
 * [Crayfish Commons](https://github.com/Islandora/Crayfish-Commons)
 * [Syn](https://github.com/Islandora/Syn)
 * [controlled\_access\_terms](https://github.com/Islandora/controlled_access_terms) (Drupal module)
-* [islandora](https://github.com/Islandora/islandora/tree/8.x-1.x) (Drupal module)
+* [islandora](https://github.com/Islandora/islandora) (Drupal module)
 * [jsonld](https://github.com/Islandora/jsonld) (Drupal module)
 * [openseadragon](https://github.com/Islandora/openseadragon) (Drupal module)
 * [islandora\_mirador](https://github.com/Islandora/islandora_mirador) (Drupal module)

docs/user-documentation/advanced-search.md

@@ -44,8 +44,8 @@ drupal modules:
 To download/enable just this module, use the following from the command line:
 
 ```bash
-composer require islandora/islandora
-drush en islandora_advanced_search
+composer require drupal/advanced_search
+drush en advanced_search
 ```
 
 ## Configuration
@@ -187,4 +187,4 @@ the block was derived from has multiple contextual filters you can choose which
 one corresponds to direct children, this will enable the recursive search
 checkbox.
 
-![screenshot of advanced search block configuration](../assets/advanced_search_advanced_search_block_settings.png)
+![screenshot of advanced search block configuration](../assets/advanced_search_advanced_search_block_settings.png)

docs/user-documentation/users.md

@@ -18,7 +18,7 @@ Additional user roles can be created and assigned customized permissions, as des
 ## Before you start
 
 - This How-To assumes a very basic familiarity with Drupal.
-- This How-To is generally applicable for any Islandora site, but the examples given are taken from an Islandora demo using the (optional) **[Islandora Starter Site](https://github.com/Islandora/islandora-starter-site)** configuration. This configuration is deployed automatically if you build your Islandora site with the appropriate options, using the [Ansible Playbook](../installation/playbook.md), [ISLE with Docker-Compose](../installation/docker-introduction.md).
+- This How-To is generally applicable for any Islandora site, but the examples given are taken from an Islandora demo using the (optional) **[Islandora Starter Site](https://github.com/Islandora/islandora-starter-site)** configuration. This configuration is deployed automatically if you build your Islandora site with the appropriate options, using the [Ansible Playbook](../installation/playbook.md), [ISLE with Docker-Compose](../installation/docker/docker-introduction.md).
 
 !!! islandora "Warning"
     If you are writing to Fedora, your username must not contain spaces.