diff --git a/docs/contributing/releasing-islandora.md b/docs/contributing/releasing-islandora.md index 83cd5dce7..3b6f3aa1c 100644 --- a/docs/contributing/releasing-islandora.md +++ b/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 diff --git a/docs/contributing/testing-a-pull-request.md b/docs/contributing/testing-a-pull-request.md new file mode 100644 index 000000000..f070240dd --- /dev/null +++ b/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/). diff --git a/docs/installation/playbook.md b/docs/installation/playbook.md index 28c2853a5..472f28002 100644 --- a/docs/installation/playbook.md +++ b/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): diff --git a/docs/technical-documentation/install-enable-drupal-modules.md b/docs/technical-documentation/install-enable-drupal-modules.md index 4a10c7b0c..b1e3dea4e 100644 --- a/docs/technical-documentation/install-enable-drupal-modules.md +++ b/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 "/:" # 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). diff --git a/docs/technical-documentation/versioning.md b/docs/technical-documentation/versioning.md index be3e9a6c8..6fba2a4ae 100644 --- a/docs/technical-documentation/versioning.md +++ b/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) diff --git a/docs/user-documentation/advanced-search.md b/docs/user-documentation/advanced-search.md index 83750b36b..677bfe8a1 100644 --- a/docs/user-documentation/advanced-search.md +++ b/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) \ No newline at end of file +![screenshot of advanced search block configuration](../assets/advanced_search_advanced_search_block_settings.png) diff --git a/docs/user-documentation/users.md b/docs/user-documentation/users.md index 1aaa87024..049166f5c 100644 --- a/docs/user-documentation/users.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 932f4bd59..cebff4e98 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,16 @@ plugins: 'contributing/docs_style_guide.md': 'contributing/docs-style-guide.md' 'contributing/readme_template.md': 'contributing/readme-template.md' 'installation/component_overview.md': 'installation/component-overview.md' + 'installation/docker-available-commands.md': 'installation/docker/isle-dc/docker-available-commands.md' + 'installation/docker-available-configuration.md': 'installation/docker/isle-dc/docker-available-configuration.md' + 'installation/docker-basic-usage.md': 'installation/docker/isle-dc/docker-basic-usage.md' + 'installation/docker-custom.md': 'installation/docker/isle-dc/docker-custom.md' + 'installation/docker-introduction.md': 'installation/docker/docker-introduction.md' + 'installation/docker-local.md': 'installation/docker/isle-dc/docker-local.md' + 'installation/docker-maintain-drupal.md': 'installation/docker/isle-dc/docker-maintain-drupal.md' + 'installation/docker-maintain-isle.md': 'installation/docker/isle-dc/docker-maintain-isle.md' + 'installation/docker-prereq.md': 'installation/docker/docker-prereq.md' + 'installation/docker-troubleshooting.md': 'installation/docker/isle-dc/docker-troubleshooting.md' 'installation/manual/configuring_drupal.md': 'installation/manual/configuring-drupal.md' 'installation/manual/installing_composer_drush_and_drupal.md': 'installation/manual/installing-composer-drush-and-drupal.md' 'installation/manual/installing_crayfish.md': 'installation/manual/installing-crayfish.md' @@ -54,6 +64,7 @@ plugins: 'installation/manual/installing_solr.md': 'installation/manual/installing-solr.md' 'installation/manual/installing_tomcat_and_cantaloupe.md': 'installation/manual/installing-tomcat-and-cantaloupe.md' 'installation/manual/preparing_a_webserver.md': 'installation/manual/preparing-a-webserver.md' + 'installation/site-template.md': 'installation/docker/site-template/site-template.md' 'technical-documentation/adding_format_jsonld.md': 'technical-documentation/adding-format-jsonld.md' 'technical-documentation/alpaca_tips.md': 'technical-documentation/alpaca-tips.md' 'technical-documentation/resizing_vm.md': 'technical-documentation/resizing-vm.md' @@ -66,6 +77,7 @@ plugins: 'user-documentation/linked_data.md': 'user-documentation/linked-data.md' 'user-documentation/metadata_harvesting.md': 'user-documentation/metadata-harvesting.md' 'user-documentation/recipes/alexa_search.md': 'user-documentation/recipes/alexa-search.md' + extra: font: @@ -259,6 +271,7 @@ nav: - 'Islandora 7': 'technical-documentation/migrate-7x.md' - Contributing: - 'How to contribute': 'contributing/CONTRIBUTING.md' + - 'Testing a Pull Request': 'contributing/testing-a-pull-request.md' - 'Running Tests': 'technical-documentation/running-automated-tests.md' - 'Checking Coding Standards': 'technical-documentation/checking-coding-standards.md' - 'Contributing Workflow': 'contributing/contributing-workflow.md' diff --git a/requirements.txt b/requirements.txt index 2358e2980..f709f72f1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -24,7 +24,7 @@ pytz==2022.7.1 PyYAML==6.0.1 pyyaml_env_tag==0.1 regex==2022.10.31 -requests==2.31.0 +requests==2.32.0 six==1.16.0 smmap==5.0.0 urllib3==1.26.18