From a6993bb8f0ad51624ccb1b78a29fe5fbb7d44ad3 Mon Sep 17 00:00:00 2001 From: Neal Date: Tue, 7 Apr 2026 08:38:55 -0400 Subject: [PATCH 1/4] add makefile for common commands, update docs to reflect current procedures --- LICENSE.txt | 2 +- Makefile | 45 +++++++++++++++++ README.md | 140 +++++++++++++++++++++++++--------------------------- 3 files changed, 113 insertions(+), 74 deletions(-) create mode 100644 Makefile diff --git a/LICENSE.txt b/LICENSE.txt index e762c7f..fb1330a 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016-2023 MLE Slone +Copyright (c) 2016-2026 MLE Slone, Neal Powers, Nicole Sand Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c4a6a30 --- /dev/null +++ b/Makefile @@ -0,0 +1,45 @@ +COMPOSE_DEV = docker compose -f docker-compose.yml -f docker-compose.dev.override.yml + +.PHONY: help dev build down test lint lint-fix check logs test-watch findingaid-sh web-sh sample + +help: ## Show this help + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}' + +dev: ## Start development environment + $(COMPOSE_DEV) up -d + +build: ## Build containers + $(COMPOSE_DEV) build + +down: ## Stop all containers + $(COMPOSE_DEV) down + +test: ## Run PHPUnit tests + $(COMPOSE_DEV) exec findingaid /opt/findingaid/vendor/bin/phpunit -c /opt/findingaid/phpunit.xml /opt/findingaid/tests + +lint: ## Run PHP_CodeSniffer (PSR-12) + $(COMPOSE_DEV) exec findingaid /opt/findingaid/vendor/bin/phpcs -w --exclude=Generic.Files.LineLength --standard=PSR12 /opt/findingaid/tests /opt/findingaid/app + +lint-fix: ## Auto-fix PHP_CodeSniffer violations (PSR-12) + $(COMPOSE_DEV) exec findingaid /opt/findingaid/vendor/bin/phpcbf --exclude=Generic.Files.LineLength --standard=PSR12 /opt/findingaid/tests /opt/findingaid/app + +check: ## Run linter and tests reports + make lint + make test + +logs: ## Tail container logs + $(COMPOSE_DEV) logs -f + +test-watch: ## Run tests on each file change (requires: watchexec) + watchexec -w app -w public -w tests --no-process-group 'make test' + +sample: ## Download and extract sample finding aid data (~1GB) + wget -O xml.tar.gz https://solrindex.uky.edu/fa/findingaid/xml.tar.gz + tar zxf xml.tar.gz + rm xml.tar.gz + +findingaid-sh: ## Shell into the findingaid container + $(COMPOSE_DEV) exec findingaid sh + +web-sh: ## Shell into the web container + $(COMPOSE_DEV) exec web sh diff --git a/README.md b/README.md index e36a77f..ca02edf 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,92 @@ -findingaid -========== +## findingaid This is a finding aid viewer intended to be used as part of a digital library. It is written to run on Linux and has not been tested with other operating systems, but should run on most Unix-like operating systems. -Caveat ------- +## Caveat -This is written specifically for the University of Kentucky Libraries and includes -some highly local assumptions. You are welcome to use and reuse this code according -to the terms of the license, but you should be aware of its opinionated nature. +This is written specifically for the University of Kentucky Libraries and +includes some highly local assumptions. You are welcome to use and reuse this +code according to the terms of the license, but you should be aware of its +opinionated nature. -Dependencies ------------- +## Developer installation -* [Composer](https://getcomposer.org) +Developer installations have been tested on Linux (through Windows with +[WSL](https://learn.microsoft.com/en-us/windows/wsl/)) and macOS. -* [JSMin](https://github.com/douglascrockford/JSMin) +### Quickstart -Installation ------------- +```shell +git clone https://github.com/uklibraries/findingaid.git +cd findingaid +make sample +make dev +``` -1. Install the dependencies. +The application should then be available at `http://localhost:8080/`. +Developers should run `make help` to see a list of helper commands through +[make](https://www.gnu.org/software/make/). -2. Extract the repository. +### Dependencies - ```shell - git clone https://github.com/uklibraries/findingaid.git /path/to/findingaid - ``` +We use [Docker](https://www.docker.com/) for reproducible environments. +Developers will want to consult the +[docker documentation for installation](https://docs.docker.com/engine/install/). +We make use of [make](https://www.gnu.org/software/make/) to manage commands, +which is a standard Linux utility and an old (but functional) version is +included with macOS. Developers can also optionally use +[watchexec](https://github.com/watchexec/watchexec) to run tests on every file +change, which will require separate installation. [Homebrew](https://brew.sh/) +is a recommended package manager that works for both Linux and macOS. Using +Docker requires access to a Linux kernel. Mac users should consider using +[Colima](https://github.com/abiosoft/colima) to access a Linux kernel. Windows +users should strongly consider working in WSL. -3. Descend into the findingaid repository. +``` +# macOS +brew install docker - ```shell - cd /path/to/findingaid - ``` +# macOS optional +brew install make watchexec +``` -4. Use Composer to install needed packages. +### Sample data -5. Generate minified JavaScript. +Finding aids must be arranged in a +[PairTree](https://confluence.ucop.edu/display/Curation/PairTree) hierarchy in +the `xml` directory. The files are not pure EAD, but must be preprocessed using +a different program. For an example, install the +[sample data](https://exploreuk.uky.edu/fa/findingaid/xml.tar.gz) (which expands +to just shy of a gigabyte): - ```shell - bash exe/build.sh - ``` +```shell +make sample +``` -6. Install your finding aid data set in the xml directory. The finding aids -must be arranged in a -[PairTree](https://confluence.ucop.edu/display/Curation/PairTree) hierarchy. -The files are not pure EAD, but must be preprocessed using a different -program. For an example, install the -[sample data](https://exploreuk.uky.edu/fa/findingaid/xml.tar.gz) -(which expands to just shy of a gigabyte): +## Coding standard - ```shell - wget https://solrindex.uky.edu/fa/findingaid/xml.tar.gz - tar zxf xml.tar.gz - ``` +This program attempts to adhere to the +[PSR-12](https://www.php-fig.org/psr/psr-12/) coding standard for all PHP code. +For convenience, the dev environment provides +[PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer/), which +detects and can repair many PSR-12 violations. Developers can use `make lint` to +get a report of linting violations, and `make lint-fix` to fix those that can be +automatically fixed. These deliberately exclude line length as a fix. -7. Create the cache directory. This must be writeable by your web server. +## Copyright - ```shell - mkdir public/cache - chown apache:apache public/cache # or appropriate similar command - ```` - -8. Connect the public directory to your website. For example, if your -website uses `/var/www/html` as its document root and permits symlinks, then -the following commands should make the finding aid viewer accessible. Some -commands might require you to become root. - - ```shell - cd /var/www/html - ln -s /path/to/findingaid/public ./findingaid - ``` - -Installation with Docker ------------------------- -If your usecase is development, the docker-compose.yml file will start an NGINX container with the appropriate volumes for development. - -Once your findingaids are installed, use `docker compose up` to start your development environment. - -Copyright ---------- - -This program is Copyright (C) 2016-2024 MLE Slone. For details, consult -LICENSE.txt. +This program is Copyright (C) 2016-2026 MLE Slone, Neal Powers, Nicole Sand. For +details, consult LICENSE.txt. This program uses the following libraries: -* Luis Almeida's [unveil.js](https://github.com/luis-almeida/unveil) -* John Dyer's [MediaElement.js](http://mediaelementjs.com) -* Marcus Ekwall's [reveal.js](http://stackoverflow.com/a/7031800/237176) -* Justin Hileman's [Mustache.php](https://github.com/bobthecow/mustache.php) -* Jan Sorgalla's [Lity](http://sorgalla.com/lity/) -* [Bootstrap](https://getbootstrap.com) -* [jQuery](https://jquery.org) -* [jQuery UI](https://jqueryui.com) +- Luis Almeida's [unveil.js](https://github.com/luis-almeida/unveil) +- John Dyer's [MediaElement.js](http://mediaelementjs.com) +- Marcus Ekwall's [reveal.js](http://stackoverflow.com/a/7031800/237176) +- Justin Hileman's [Mustache.php](https://github.com/bobthecow/mustache.php) +- Jan Sorgalla's [Lity](http://sorgalla.com/lity/) +- [Bootstrap](https://getbootstrap.com) +- [jQuery](https://jquery.org) +- [jQuery UI](https://jqueryui.com) From f6b966f6e33d833e3f33d69fcf138f6964982c65 Mon Sep 17 00:00:00 2001 From: Neal Date: Tue, 7 Apr 2026 10:27:00 -0400 Subject: [PATCH 2/4] reorder for alphabetic order --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ca02edf..de0a6e3 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ automatically fixed. These deliberately exclude line length as a fix. ## Copyright -This program is Copyright (C) 2016-2026 MLE Slone, Neal Powers, Nicole Sand. For +This program is Copyright (C) 2016-2026 Neal Powers, Nicole Sand, MLE Slone. For details, consult LICENSE.txt. This program uses the following libraries: From e9d6787348df69af72a1b3d965a83a2fe391443c Mon Sep 17 00:00:00 2001 From: Nicole Date: Tue, 14 Apr 2026 12:52:14 +0000 Subject: [PATCH 3/4] revert changes to copyright info. Relates to #45 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de0a6e3..e11ae7c 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ automatically fixed. These deliberately exclude line length as a fix. ## Copyright -This program is Copyright (C) 2016-2026 Neal Powers, Nicole Sand, MLE Slone. For +This program is Copyright (C) 2016-2024 MLE Slone. For details, consult LICENSE.txt. This program uses the following libraries: From 49b8d374f1cc6065e069e8dd4dcc03c056b45d57 Mon Sep 17 00:00:00 2001 From: Nicole Date: Tue, 14 Apr 2026 12:54:11 +0000 Subject: [PATCH 4/4] revert changes to copyright info. Relates to #45 --- LICENSE.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE.txt b/LICENSE.txt index fb1330a..e762c7f 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016-2026 MLE Slone, Neal Powers, Nicole Sand +Copyright (c) 2016-2023 MLE Slone Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal