{"id":42925068,"url":"https://github.com/tulibraries/tul_hyku_knapsack","last_synced_at":"2026-01-30T18:07:44.102Z","repository":{"id":235502338,"uuid":"790820078","full_name":"tulibraries/tul_hyku_knapsack","owner":"tulibraries","description":"Temple Libraries wrapper for Hyku application.","archived":false,"fork":false,"pushed_at":"2025-11-13T22:04:37.000Z","size":174,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-11-14T00:10:27.438Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tulibraries.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-23T15:33:13.000Z","updated_at":"2025-03-10T15:56:23.000Z","dependencies_parsed_at":"2024-04-25T21:28:28.756Z","dependency_job_id":"0d4153e9-9131-4919-9c7e-4c6600c6b3c2","html_url":"https://github.com/tulibraries/tul_hyku_knapsack","commit_stats":null,"previous_names":["tulibraries/tul_hyku_knapsack"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tulibraries/tul_hyku_knapsack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Ftul_hyku_knapsack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Ftul_hyku_knapsack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Ftul_hyku_knapsack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Ftul_hyku_knapsack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tulibraries","download_url":"https://codeload.github.com/tulibraries/tul_hyku_knapsack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Ftul_hyku_knapsack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28917034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T16:37:38.804Z","status":"ssl_error","status_checked_at":"2026-01-30T16:37:37.878Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-30T18:07:43.468Z","updated_at":"2026-01-30T18:07:44.089Z","avatar_url":"https://github.com/tulibraries.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [HykuKnapsack](#hykuknapsack)\n  - [Introduction](#introduction)\n    - [Precedence](#precedence)\n  - [Usage](#usage)\n    - [Creating Your Knapsack](#creating-your-knapsack)\n      - [New Repository](#new-repository)\n      - [Fork on Github](#fork-on-github)\n    - [Hyku and HykuKnapsack](#hyku-and-hykuknapsack)\n    - [Overrides](#overrides)\n    - [Deployment scripts](#deployment-scripts)\n    - [Theme files](#theme-files)\n    - [Gems](#gems)\n  - [Converting a Fork of Hyku Prime to a Knapsack](#converting-a-fork-of-hyku-prime-to-a-knapsack)\n  - [Installation](#installation)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# HykuKnapsack\n\n[Hyku Knapsack](https://github.com/samvera-labs/hyku_knapsack) is a little wrapper around Hyku to make development and deployment easier. Primary goals of this project\ninclude making contributing back to the Hyku project easier and making upgrades a snap.\n\n## Introduction\n\n[Hyku](https://github.com/samvera/hyku) is a Rails application that leverages Rails Engines and other gems to provide functionality.  A Hyku Knapsack is also a Rails engine, but it integrates differently than other engines.\n\n### Precedence\n\nIn a traditional setup, a Rails' application's views, translations, and code supsedes all other gems and engines.  However, we have setup Hyku Knapsack to have a higher load precedence than the underlying Hyku application.\n\nThe goal being that a Hyku Knapsack should make it easier to maintain, upgrade, and contribute fixes back to Hyku.\n\nSee [Overrides](#overrides) for more discussion on working with a Hyku Knapsack.\n\n## Usage\n\n### Creating Your Knapsack\n\nIn working on a Hyku Knapsack, you want to be able to track changes in the upstream knapsack as well as make local changes for your application.  Start by making a clone.  You can do this by:\n\n- _Preferred_ Creating a [New Repository](#new-repository) and pushing your local clone\n- Creating a [Fork on Github](#fork-on-github)\n\n#### New Repository\n\nIn your Repository host of choice, create a new (and for now empty) repository.\n\n- `$PROJECT_NAME` must only contain letters, numbers and underscores due to a bundler limitation.\n- `$NEW_REPO_URL` is the location of your application's knapsack git project (e.g. https://github.com/my-org/my_org_knapsack)\n\n```bash\ngit clone https://github.com/samvera-labs/hyku_knapsack $PROJECT_NAME_knapsack\ncd $PROJECT_NAME_knapsack\ngit remote rename origin prime\ngit remote add origin $NEW_REPO_URL\ngit branch -M main\ngit push -u origin main\n```\n\nNaming the `samvera-labs/hyku_knapsack` as `prime` helps clarify what we mean.  In conversations about Hyku instances, invariably we use the language of Prime to reflect what's in Samvera's repositories.  By using that language for remotes, we help reinforce the concept that `https://github.com/samvera/hyku` is Hyku prime and `https://github.com/samvera-labs/hyku_knapsack` is Knapsack prime.\n\n#### Fork on Github\n\nIf you choose to fork Knapsack, be aware that this will impact how you manage pull requests via Github.  Namely as you submit PRs on your Fork, the UI might default to applying that to the fork's origin (e.g. Knapsack upstream).\n\nTo ease synchronization of your Knapsack and Knapsack “prime”, consider adding knapsack prime as a remote:\n\n```bash\ncd $PROJECT_NAME_knapsack\ngit remote add prime https://github.com/samvera-labs/hyku_knapsack\n```\n\n### Hyku and HykuKnapsack\n\nYou run your Hyku application by way of the HykuKnapsack.  As mentioned, the HykuKnapsack contains your application's relevant information for running an instance of Hyku.\n\nThere are two things you need to do:\n\n- Ensure you have the [reserved branch](#reserved-branch)\n- Initialize the [Hyku submodule](#hyku-submodule)\n\n#### Reserved Branch\n\nKnapsack turns the assumptions of a Rails engine upside-down; the application overlays traditional engines, but Knapsack overlays the application.  As such the Gemfile declared in Hyku does some bundler trickery.\n\nIn the `$PROJECT_NAME_knapsack` directory, you need to run the following:\n\n```bash\ngit fetch prime\ngit checkout prime/required_for_knapsack_instances\ngit switch -c required_for_knapsack_instances\n```\n\nFor Hyku to build with Knapsack, we need a local branch named `required_for_knapsack_instances`.  _Note:_ As we work more with Knapsack maintenance there may be improvements to this shim.\n\n#### Hyku Submodule\n\nA newly cloned knapsack will have an empty `./hyrax-webapp` directory.  That is where the Hyku application will exist.  The version of Hyku is managed via a [Git submodule](https://git-scm.com/docs/git-submodule).\n\nTo bring that application into your knapsack, you will need to initialize the Hyku submodule:\n\n```bash\n❯ git submodule init\nSubmodule 'hyrax-webapp' (https://github.com/samvera/hyku.git) registered for path 'hyrax-webapp'\n```\n\nThen update the submodule to clone the remote Hyku repository into `./hyrax-webapp`.  The `KNAPSACK-SPECIFIED-HYKU-REPOSITORY-SHA` is managed within the Hyku Knapsack (via Git submodules).\n\n```bash\n❯ git submodule update\nCloning into '/path/to/$PROJECT_NAME_knapsack/hyrax-webapp'...\nSubmodule path 'hyrax-webapp': checked out '\u003cKNAPSACK-SPECIFIED-HYKU-REPOSITORY-SHA\u003e'\n```\n\nThe configuration of the submodule can be found in the `./.gitmodules` file.  During development, we've specified the submodule's branch (via `git submodule set-branch --branch \u003cNAME\u003e -- ./hyrax-webapp`).\n\nBelow is an example of our Adventist Knapsack submodule.\n\n```\n❯ cat .gitmodules\n[submodule \"hyrax-webapp\"]\n\tpath = hyrax-webapp\n\turl = https://github.com/samvera/hyku.git\n\tbranch = adventist_dev\n```\n\nWhen you want to bring down an updated version of your Hyku submodule, use the following:\n\n```bash\n\u003e git submodule update --remote\n```\n\nThis will checkout the submodule to the HEAD of the specified branch.\n\n### Overrides\n\nBefore overriding anything, please think hard (or ask the community) about whether what you are working on is a bug or feature that can apply to Hyku itself. If it is, please make a branch in your Hyku checkout (`./hyrax-webapp`) and do the work there. [See here](https://github.com/samvera-labs/hyku_knapsack/wiki/Hyku-Branches) for more information about working with Hyku branches in your Knapsack\n\nAdding decorators to override features is fairly simple. We do recommend some best practices [found here](https://github.com/samvera-labs/hyku_knapsack/wiki/Decorators-and-Overrides)\n\nAny file with `_decorator.rb` in the app or lib directory will automatically be loaded along with any classes in the app directory.\n\n### Deployment scripts\n\nDeployment code can be added as needed.\n\n### Theme files\n\nTheme files (views, css, etc) can be added in the the Knapsack. We recommend adding an override comment as [described here](https://github.com/samvera-labs/hyku_knapsack/wiki/Decorators-and-Overrides)\n\n### Gems\n\nIt can be useful to add additional gems to the bundle. This can be done w/o editing Hyku by adding them to the [./bundler.d/example.rb](./bundler.d/example.rb].  [See the bundler-inject documentation for more details](https://github.com/kbrock/bundler-inject/) on overriding and adding gems.\n\n**NOTE:** Do not add gems to the gemspec nor Gemfile.  When you add to the knapsack Gemfile/gemspec, when you bundle, you'll update the Hyku Gemfile; which will mean you might be updating Hyku prime with knapsack installation specific dependencies.  Instead add gems to `./bundler.d/example.rb`.\n\n## Converting a Fork of Hyku Prime to a Knapsack\n\nPrior to Hyku Knapsack, organizations would likely clone [Hyku](https://github.com/samvera/hyku) and begin changing the code to reflect their specific needs.  The result was that the clone would often drift away from Samvera Hyku version.  This drift created challenges in reconciling what you had changed locally as well as how you could easily contribute some of your changes upstream to Samvera's Hyku.\n\nWith Hyku Knapsack, the goal is three-fold:\n\n1. To isolate the upstream Samvera Hyku code from your local modifications.  This isolation is via the `./hyrax-webapp` submodule.\n2. To provide a clear and separate space for extending/overriding Hyku functionality.\n3. To provide a cleaner pathway for upgrading the underlying Hyku application; for things such as security updates, bug fixes, and upstream enhancements.\n\nFrom those goals, we can begin to see what we want in our Hyku Knapsack:\n\n1. Files that are not found in Hyku\n2. Or files that are different from what is in Hyku (and thus will be loaded at a higher precedence)\n\nAssuming you're working from a fork of Samvera's Hyku repository, these are some general steps.  First clone the Hyku Knapsack ([see the Usage section](#usage)).  You'll also want to initialize the git submodule.  Point the `./hyrax-webapp` to the branch/SHA of Samvera's Hyku that you want to use; **Note:** that version must include a `gem 'hyku_knapsack'` declaration (e.g. introduced in  [7853fe5d](https://github.com/samvera/hyku/blob/7853fe5d79afd9d90cec3b9ef666681b287ef4d0/Gemfile)).\n\nYou'll also want to have a local copy of your Hyku application.\n\nYou can then use `bin/knapsacker` to generate a list of files that need review.  That will give you a list of:\n\n- Files in your Hyku that are exact duplicates of upstream Hyku file (prefix with `=`)\n- Files that are in your Hyku but not in upstream Hyku (prefixed with `+`)\n- Files that are changed in your Hyku relative to upstream Hyku (prefix with `Δ`)\n\nYou can pipe that output into a file and begin working on reviewing and moving files into the Knapsack.  This is not an easy to automate task, after all we're paying down considerable tech debt.\n\nOnce you've moved over the files, you'll want to boot up your Knapsack and then work through your test plan.\n\nThe `bin/knapsacker` is general purpose.  I have used it to compare one non-Knapsack Hyku instance against Samvera's Hyku.  I have also used it to compare a Knapsack's file against it's submodule Hyku instance.\n\n## Installation\n\nIf not using a current version, add this line to Hyku's Gemfile:\n\n```ruby\ngem \"hyku_knapsack\", github: 'samvera-labs/hyku_knapsack', branch: 'main'\n```\n\nAnd then execute:\n```bash\n$ bundle\n```\n\n## Contributing\n\nContribution directions go here.\n\n## License\n\nThe gem is available as open source under the terms of the [Apache 2.0](https://opensource.org/license/apache-2-0/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftulibraries%2Ftul_hyku_knapsack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftulibraries%2Ftul_hyku_knapsack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftulibraries%2Ftul_hyku_knapsack/lists"}