Skip to content

Update dev and deploy documentation to reflect new github actions #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adamshire123 wants to merge 3 commits into
base: mit-main
Choose a base branch
from
Open

Update dev and deploy documentation to reflect new github actions #71

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d107a97
Update documentation to reflect new github actions
adamshire123 Jul 29, 2026
954d251
Apply suggestions from code review
adamshire123 Jul 29, 2026
49a31e0
fix typo
adamshire123 Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 38 additions & 34 deletions mit-readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,41 @@
* See instructions below for syncing with the forked repository

# Development workflows
## Making style or markup changes
1. If not already installed, clone this repository from GitHub, install the NDE development environment following the instructions in README.md,
2. Develop and test your changes locally following the instructions in README.MD for using the NDE development environment.
3. Push a branch with your changes to our GitHub repository and open a PR to merge that branch into `mit-main` and request a review
4. Once your PR is reviewed and approved, merge your changes into `mit-main`

1. If not already installed, clone this repository from GitHub and install the NDE development environment following the instructions in README.md.
2. Develop and test your changes locally following the instructions in README.md for using the NDE development environment.
3. Push a branch with your changes to our GitHub repository and open a PR to merge that branch into `mit-main` and request a review.
4. Once your PR is reviewed and approved, merge your changes into `mit-main`.

## Testing changes in a local development environment as part of code review
For style and markup changes, testing locally in the dev environment is usually sufficient
Testing locally in the dev environment is usually sufficient for code review.
1. Clone this repository from GitHub (or just `git pull origin [new-nde-changes]` if you already have our NDE development environment installed locally)
2. If not already installed, install the NDE development environment following the instructions in README.md
3. Switch to the branch being tested `git checkout [new-nde-changes]`
4. Run the development server with proxy `npm run start:proxy`, following the instructions in README.md and confirm the changes work as expected
2. If not already installed, install the NDE development environment following the instructions in README.md.
3. Switch to the branch being tested: `git checkout [new-nde-changes]`.
4. Run the development server with proxy `npm run start:proxy`, following the instructions in README.md and confirm the changes work as expected.

## Testing changes by deploying to Primo testing environment as part of code review - An Alma Admin with access to Discovery Configuration must take these steps
In some cases it may be desireable to test changes in a production-like environment in addition to the local dev environment.
1. Clone this repository from GitHub (or just `git pull origin [new-nde-changes]` if you already have our NDE development environment installed locally)
2. If not already installed, install the NDE development environment following the instructions in README.md
3. Switch to the branch being tested `git checkout [new-nde-changes]`
4. **IMPORTANT** - In `build-settings.env` set `VIEW_ID=NDE_DEV`
5. Run the build command `npm run build` following the instructions in README.md.
6. As a result of running the build command a new .zip file containing a Primo Customization Package will be created in `/dist`
7. Upload the .zip file to the `NDE_DEV` view via the Alma admin interface following the instructions at https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/020Primo_VE/Primo_VE_(English)/050Display_Configuration/010Configuring_Discovery_Views_for_Primo_VE#Managing_Customization_Packages
8. Test the changes at https://mit.primo.exlibrisgroup.com/nde/home?vid=01MIT_INST:NDE_DEV

## Deploying to our production NDE view - An Alma Admin with access to Discovery Configuration must take these steps
1. Clone this repository from GitHub (or just `git pull origin mit-main` if you already have a local copy of our NDE development environment installed)
2. If not already installed, install the NDE development environment following the instructions in README.md
3. switch to the production branch `git checkout mit-main`
4. Run the build command `npm run build` following the instructions in README.md
5. As a result of running the build command a new .zip file representing a Primo Customization Package will land in `/dist`
6. Upload the .zip file to production NDE view via the Alma admin interface following the instructions at https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/020Primo_VE/Primo_VE_(English)/050Display_Configuration/010Configuring_Discovery_Views_for_Primo_VE#Managing_Customization_Packages
In some cases it may be desirable to test changes in a production-like environment in addition to the local dev environment.
1. Push a branch with your changes to GitHub.
2. Run the GitHub Actions workflow for a development build targeting the branch you want to test.
3. The action's default setting creates a customization package for the NDE_DEV view, but this can be changed if you want to deploy the customization package to a different Primo view.
4. Download the customization package from the Development build action summary in the repo after the action completes
5. Upload the .zip file to the target Primo view via the Alma admin interface following the instructions at https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/020Primo_VE/Primo_VE_(English)/050Display_Configuration/010Configuring_Discovery_Views_for_Primo_VE#Managing_Customization_Packages (Requires user with write access to Discovery Configuration in Alma)
6. Test the changes at https://mit.primo.exlibrisgroup.com/nde/home?vid=01MIT_INST:{view}

## Deploying to production STAGE view
In order to test changes against the most production-like environment, it is recommended to create a short-lived clone of the production view (`NDE`) `STAGE`
1. Delete the existing `STAGE` view in production Primo if there is one.
2. Clone the `NDE` view and name the new view `STAGE`.
3. When a branch is merged into `mit-main`, a customization package targeting a `STAGE` view is created automatically.
4. Download the customization package from the Stage build action summary in the GitHub repo.
5. Upload the .zip file to the `STAGE` view via the Alma admin interface following the instructions at https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/020Primo_VE/Primo_VE_(English)/050Display_Configuration/010Configuring_Discovery_Views_for_Primo_VE#Managing_Customization_Packages (Requires user with write access to Discovery Configuration in Alma)

## Deploying to production NDE view
1. Tag a new release on the `mit-main` branch in GitHub.
2. This will automatically run tests and generate a customization package targeting the `NDE` view.
- Note that the build artifact (01MIT_INST-NDE.zip) will land in the assets section of the release, not in the action summary: https://github.com/MITLibraries/Primo-NDE-Customization-Package/releases
3. Deploy the .zip file to production `NDE` view via the Alma admin interface following the instructions at https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/020Primo_VE/Primo_VE_(English)/050Display_Configuration/010Configuring_Discovery_Views_for_Primo_VE#Managing_Customization_Packages (Requires user with write access to Discovery Configuration in Alma)

## Syncing with the upstream forked repository.
This repository is forked from https://github.com/ExLibrisGroup/customModule
Expand All @@ -45,13 +49,13 @@ Take the following steps to sync our local repository with changes from this ups

Note that our `main` branch tracks the upstream `main` branch:

1. Sync our `main` branch in GitHub using the `sync fork` button
2. Assuming the NDE development environment is running locally, `git pull origin main` to pull down our local copy of the upstream `main`
3. `git checkout mit-main` and make sure you have the most recent commits `git pull origin mit-main`
4. Create a temporary local branch e.g. `git checkout -B test-upstream-changes`
5. `git merge main` and confirm that the upstream changes haven't broken anything.
6. Delete your temporary branch
7. Open a PR to merge our `main` into our `mit-main`
8. Follow steps above for testing and deploying to production
1. Sync our `main` branch in GitHub using the `sync fork` button.
2. Assuming the NDE development environment is running locally, run `git pull origin main` to pull down our local copy of the upstream `main`.
3. Run `git checkout mit-main` and make sure you have the most recent commits with `git pull origin mit-main`.
4. Create a temporary local branch, e.g., `git checkout -B test-upstream-changes`.
5. Run `git merge main` and confirm that the upstream changes haven't broken anything.
6. Delete your temporary branch.
7. Open a PR to merge our `main` into our `mit-main`.
8. Follow the steps above for testing and deploying to production.