From 96a6e7f832eb3129d1615a73776f14bc83a1bc30 Mon Sep 17 00:00:00 2001 From: Beecher Baker Date: Thu, 5 Sep 2024 09:48:17 -0400 Subject: [PATCH 01/10] fix production version base url --- config/header.yml | 2 +- config/router.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/config/header.yml b/config/header.yml index 57b8041..26c85c0 100644 --- a/config/header.yml +++ b/config/header.yml @@ -9,4 +9,4 @@ link: /about - label: Source - link: https://github.com/neolefty/taxonpages-dev/ \ No newline at end of file + link: https://github.com/PurdueEntomologicalResearchCollection/taxonpages/ \ No newline at end of file diff --git a/config/router.yml b/config/router.yml index 4b33905..684e65b 100644 --- a/config/router.yml +++ b/config/router.yml @@ -1,3 +1,3 @@ --- - base_url: /taxonpages-dev/ + base_url: /taxonpages/ hash_mode: true \ No newline at end of file From 8a769fced6cda949fab0213ecd1fde22fd027fd2 Mon Sep 17 00:00:00 2001 From: Beecher Baker Date: Thu, 5 Sep 2024 19:09:08 -0400 Subject: [PATCH 02/10] more development instructions --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 9451db5..887469a 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ Each is built using to GitHub Actions, following [these instructions](https://gi ## Local Dev Setup +Option 1: Work on both the prod and dev sites from a single local repo. + ```bash # 1. Clone the production repo git clone git@github.com:PurdueEntomologicalResearchCollection/taxonpages.git @@ -34,6 +36,24 @@ npm run dev # TODO: Explain how to clean up after that funky branch setup ``` +Option 2: Work only in one of the repos (simpler, but you can't commit changes to the other repo): + +```bash: +# 1. Clone the repo you want to work on -- in this example, it's dev +git clone git@github.com:PurdueEntomologicalResearchCollection/taxonpages-dev.git +cd taxonpages-dev +# 2. Do TaxonPages' funky branch setup +git checkout main +git checkout setup . +# 2. Run locally +npm install +npm run dev +# 3. Make changes -- http://localhost:5173/taxonpages-dev/, edit code, and the app will hot-reload +# 4. Commit changes, being careful to not add foreign objects from the `setup` branch +git add . +# TODO finish this +git commit -m "Your message here" +``` --- # TaxonPages From 17c9b792deafc987c8a31418bf9f6a058ebf323a Mon Sep 17 00:00:00 2001 From: Beecher Baker Date: Thu, 3 Oct 2024 11:07:27 -0400 Subject: [PATCH 03/10] update reference URLs --- config/project.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/config/project.yml b/config/project.yml index 30497ed..f4fddd7 100644 --- a/config/project.yml +++ b/config/project.yml @@ -1,5 +1,5 @@ --- project_name: Search PERC - project_citation: Search PERC. 2024. https://neolefty.github.io/taxonpages/ - project_url: https://neolefty.github.io/taxonpages/ + project_citation: Search PERC. 2024. https://ag.purdue.edu/department/entm/perc/ + project_url: https://github.com/PurdueEntomologicalResearchCollection/taxonpages/ project_authors: Aaron Smith, Christopher Wirth From 429dd454d7a3dacb8fbb58f6abf64b1dfaf660ec Mon Sep 17 00:00:00 2001 From: Beecher Baker Date: Thu, 21 Nov 2024 16:47:49 -0500 Subject: [PATCH 04/10] Update README.md --- README.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 887469a..441f57e 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,22 @@ -# This Fork of [TaxonPages](https://github.com/SpeciesFileGroup/taxonpages) +# Purdue Entomology's [TaxonPages](https://github.com/SpeciesFileGroup/taxonpages) -It has two repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582): +It has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582): -* Production: [PERC TaxonPages](https://PurdueEntomologicalResearchCollection.github.io/taxonpages/) - * Deployed to the https://ag.purdue.edu/department/entm/perc/search-collection.html -* Dev / Preview: [PERC Dev TaxonPages](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-dev/) - * Deployed to the https://ag.purdue.edu/department/agit/test/perc/ +# Production Github Pages: [taxonpages](https://PurdueEntomologicalResearchCollection.github.io/taxonpages/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages/ +# Production Cascade: [taxonpages-deploy](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/entm/perc/search-collection.html +# Development Github Pages: [taxonpages-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-dev/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ +# Development Cascade: [taxonpages-deploy-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy-dev/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/agit/test/perc/ -There is one divergence between the two: in the `setup` branch, in `router.yml`:`base_url` is set to -* `/taxonpages-dev/` in the `dev` repo, and -* `/taxonpages/` in the `production` repo. +There is one divergence between them: in the `setup` branch, in `router.yml`:`base_url` is set to: +* `/taxonpages/` in the `taxonpages` repo +* `/entm/perc/search-collection.html` in the `taxonpages-deploy` repo +* `/taxonpages-dev/` in the `taxonpages-dev` repo +* `/department/agit/test/perc/` in the `taxonpages-deploy-dev` repo Each is built using to GitHub Actions, following [these instructions](https://github.com/SpeciesFileGroup/taxonpages). +## TODO: Explain how to deploy to Cascade + ## Local Dev Setup Option 1: Work on both the prod and dev sites from a single local repo. @@ -33,7 +37,7 @@ npm install npm run dev # 4. Make changes -- http://localhost:5173/taxonpages-dev/, edit code, and the app will hot-reload # 5. Commit changes -# TODO: Explain how to clean up after that funky branch setup +# **TODO: Explain how to clean up after that funky branch setup** ``` Option 2: Work only in one of the repos (simpler, but you can't commit changes to the other repo): @@ -51,7 +55,7 @@ npm run dev # 3. Make changes -- http://localhost:5173/taxonpages-dev/, edit code, and the app will hot-reload # 4. Commit changes, being careful to not add foreign objects from the `setup` branch git add . -# TODO finish this +# **TODO finish this? Or delete?** git commit -m "Your message here" ``` --- From 27628be0c7e1ff87c8d8ff5b3ddffbf9543e4204 Mon Sep 17 00:00:00 2001 From: Beecher Baker Date: Thu, 21 Nov 2024 16:48:07 -0500 Subject: [PATCH 05/10] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 441f57e..3df303d 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ It has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582): -# Production Github Pages: [taxonpages](https://PurdueEntomologicalResearchCollection.github.io/taxonpages/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages/ -# Production Cascade: [taxonpages-deploy](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/entm/perc/search-collection.html -# Development Github Pages: [taxonpages-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-dev/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ -# Development Cascade: [taxonpages-deploy-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy-dev/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/agit/test/perc/ +1. Production Github Pages: [taxonpages](https://PurdueEntomologicalResearchCollection.github.io/taxonpages/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages/ +2. Production Cascade: [taxonpages-deploy](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/entm/perc/search-collection.html +3. Development Github Pages: [taxonpages-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-dev/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ +4. Development Cascade: [taxonpages-deploy-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy-dev/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/agit/test/perc/ There is one divergence between them: in the `setup` branch, in `router.yml`:`base_url` is set to: * `/taxonpages/` in the `taxonpages` repo From 02af8cc3b62c9d47c69efa79b04979d670bc77a4 Mon Sep 17 00:00:00 2001 From: Beecher Baker Date: Thu, 21 Nov 2024 16:52:03 -0500 Subject: [PATCH 06/10] Move list of repos to a table --- README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3df303d..d402fcb 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,13 @@ It has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582): -1. Production Github Pages: [taxonpages](https://PurdueEntomologicalResearchCollection.github.io/taxonpages/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages/ -2. Production Cascade: [taxonpages-deploy](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/entm/perc/search-collection.html -3. Development Github Pages: [taxonpages-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-dev/) — auto-deployed to https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ -4. Development Cascade: [taxonpages-deploy-dev](https://PurdueEntomologicalResearchCollection.github.io/taxonpages-deploy-dev/) — configured to run in Cascade (requires manual deployment): https://ag.purdue.edu/department/agit/test/perc/ +| Repo | Description | Deployed to | Method | +|--|--|--|--| +| taxonpages | Github Pages | https://purdueentomologicalresearchcollection.github.io/taxonpages/ | automatic | +| taxonpages-deploy | Cascade | https://ag.purdue.edu/department/entm/perc/search-collection.html | manual | +| taxonpages-dev | Github Pages | https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ | automatic | +| taxonpages-deploy-dev | Cascade | https://ag.purdue.edu/department/agit/test/perc/ | manual | + There is one divergence between them: in the `setup` branch, in `router.yml`:`base_url` is set to: * `/taxonpages/` in the `taxonpages` repo From 2935310bdcae5b82169894c49995c503b49bec6f Mon Sep 17 00:00:00 2001 From: Beecher Baker Date: Fri, 22 Nov 2024 08:25:16 -0500 Subject: [PATCH 07/10] Add links to actions; wording --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d402fcb..7284271 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@ It has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582): -| Repo | Description | Deployed to | Method | +| Repo | Destination | Deployed URL | Method | |--|--|--|--| | taxonpages | Github Pages | https://purdueentomologicalresearchcollection.github.io/taxonpages/ | automatic | -| taxonpages-deploy | Cascade | https://ag.purdue.edu/department/entm/perc/search-collection.html | manual | +| taxonpages-deploy | Cascade | https://ag.purdue.edu/department/entm/perc/search-collection.html | [manual](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy/actions) | | taxonpages-dev | Github Pages | https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ | automatic | -| taxonpages-deploy-dev | Cascade | https://ag.purdue.edu/department/agit/test/perc/ | manual | +| taxonpages-deploy-dev | Cascade | https://ag.purdue.edu/department/agit/test/perc/ | [manual](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions) | There is one divergence between them: in the `setup` branch, in `router.yml`:`base_url` is set to: From 8f4a2af77e2e5b0c439d027e1d7cf70967ada190 Mon Sep 17 00:00:00 2001 From: W Beecher Baker Date: Fri, 22 Nov 2024 08:58:43 -0500 Subject: [PATCH 08/10] describe all 4 repos --- README.md | 31 ++++++++++++------------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 7284271..9bbad08 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,17 @@ # Purdue Entomology's [TaxonPages](https://github.com/SpeciesFileGroup/taxonpages) -It has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582): +It has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582). They diverge only in their `base_url` in the file `config/router.yml`. -| Repo | Destination | Deployed URL | Method | -|--|--|--|--| -| taxonpages | Github Pages | https://purdueentomologicalresearchcollection.github.io/taxonpages/ | automatic | -| taxonpages-deploy | Cascade | https://ag.purdue.edu/department/entm/perc/search-collection.html | [manual](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy/actions) | -| taxonpages-dev | Github Pages | https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ | automatic | -| taxonpages-deploy-dev | Cascade | https://ag.purdue.edu/department/agit/test/perc/ | [manual](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions) | +| Repo | Destination | `base_url` in `router.yml` | +|--|--|--| +| taxonpages | Github Pages:
https://purdueentomologicalresearchcollection.github.io/taxonpages/ | `/taxonpages/` | +| taxonpages-deploy | Cascade — see [action log](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy/actions) for deployment:
https://ag.purdue.edu/department/entm/perc/search-collection.html | `/department/entm/perc/search-collection.html` | +| taxonpages-dev | Github Pages:
https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ | `/taxonpages-dev/` | +| taxonpages-deploy-dev | Cascade — see [action log](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions) for deployment:
https://ag.purdue.edu/department/agit/test/perc/ | `/department/agit/test/perc/` | +Each is built using to GitHub Actions, following [these instructions](https://github.com/SpeciesFileGroup/taxonpages). Deployment is automatic for those hosted on Github Pages, but for Cascade it requires manual steps of copying files. For now. In the future, hopefully we can automate Cascade deployments using the [Cascade API](https://www.hannonhill.com/cascadecms/latest/developing-in-cascade/rest-api/operations.html). -There is one divergence between them: in the `setup` branch, in `router.yml`:`base_url` is set to: -* `/taxonpages/` in the `taxonpages` repo -* `/entm/perc/search-collection.html` in the `taxonpages-deploy` repo -* `/taxonpages-dev/` in the `taxonpages-dev` repo -* `/department/agit/test/perc/` in the `taxonpages-deploy-dev` repo - -Each is built using to GitHub Actions, following [these instructions](https://github.com/SpeciesFileGroup/taxonpages). - -## TODO: Explain how to deploy to Cascade +### TODO: Explain how to deploy to Cascade ## Local Dev Setup @@ -31,14 +24,14 @@ cd taxonpages # 2. Add the dev repo as a remote and configure dev branches git remote add dev git@github.com:PurdueEntomologicalResearchCollection/taxonpages-dev.git git fetch dev -git branch -u dev/setup dev-setup -git branch -u dev/main dev-main +git checkout -b dev-setup dev/setup +git checkout -b dev-main dev/main # 3. Run dev-main branch locally git checkout dev-main git checkout dev-setup . # Yes, this is a funky thing to do, and you will have to clean up before committing npm install npm run dev -# 4. Make changes -- http://localhost:5173/taxonpages-dev/, edit code, and the app will hot-reload +# 4. Make changes -- http://localhost:5173/taxonpages-dev/, edit code, and the app will hot-reload # 5. Commit changes # **TODO: Explain how to clean up after that funky branch setup** ``` From 4f5b641b19cbef1e8bcfcf3c78598e3178b16743 Mon Sep 17 00:00:00 2001 From: W Beecher Baker Date: Fri, 22 Nov 2024 11:53:25 -0500 Subject: [PATCH 09/10] elaborate on development instructions --- README.md | 76 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 50 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 9bbad08..348a8e2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Purdue Entomology's [TaxonPages](https://github.com/SpeciesFileGroup/taxonpages) -It has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582). They diverge only in their `base_url` in the file `config/router.yml`. +**Purdue Entomological Research Collection** (PERC) homepage: https://ag.purdue.edu/department/entm/perc/ + +The PERC instance of TaxonPages has four repos, each with its own GitHub Pages site — because a repo [can only have a single GitHub Pages site](https://github.com/orgs/community/discussions/21582). They diverge only in their `base_url` in the file `config/router.yml`. | Repo | Destination | `base_url` in `router.yml` | |--|--|--| @@ -9,51 +11,73 @@ It has four repos, each with its own GitHub Pages site — because a repo [can o | taxonpages-dev | Github Pages:
https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ | `/taxonpages-dev/` | | taxonpages-deploy-dev | Cascade — see [action log](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions) for deployment:
https://ag.purdue.edu/department/agit/test/perc/ | `/department/agit/test/perc/` | -Each is built using to GitHub Actions, following [these instructions](https://github.com/SpeciesFileGroup/taxonpages). Deployment is automatic for those hosted on Github Pages, but for Cascade it requires manual steps of copying files. For now. In the future, hopefully we can automate Cascade deployments using the [Cascade API](https://www.hannonhill.com/cascadecms/latest/developing-in-cascade/rest-api/operations.html). +Each uses GitHub Actions, following [these instructions](https://github.com/SpeciesFileGroup/taxonpages). Deployment is automatic for those hosted on Github Pages, but for Cascade it requires manual steps of copying files. For now. In the future, hopefully we can automate Cascade deployments using the [Cascade API](https://www.hannonhill.com/cascadecms/latest/developing-in-cascade/rest-api/operations.html). ### TODO: Explain how to deploy to Cascade -## Local Dev Setup +## Local Development + +You'll need to clone multiple repos into a _single local git repo_. This may be a new experience, even for seasoned `git` users! -Option 1: Work on both the prod and dev sites from a single local repo. +1. Clone the production repo, like normal. ```bash -# 1. Clone the production repo git clone git@github.com:PurdueEntomologicalResearchCollection/taxonpages.git cd taxonpages -# 2. Add the dev repo as a remote and configure dev branches +``` + +2. Add the dev repo as a remote and configure dev branches. + +```bash git remote add dev git@github.com:PurdueEntomologicalResearchCollection/taxonpages-dev.git git fetch dev git checkout -b dev-setup dev/setup git checkout -b dev-main dev/main -# 3. Run dev-main branch locally +``` + +3. Run the `dev-main` branch locally. You can follow the usual dev cycle — make changes , edit code, commit, repeat. + +```bash git checkout dev-main git checkout dev-setup . # Yes, this is a funky thing to do, and you will have to clean up before committing npm install npm run dev -# 4. Make changes -- http://localhost:5173/taxonpages-dev/, edit code, and the app will hot-reload -# 5. Commit changes -# **TODO: Explain how to clean up after that funky branch setup** ``` -Option 2: Work only in one of the repos (simpler, but you can't commit changes to the other repo): +Open http://localhost:5173/taxonpages-dev/ to try it out, see changes hot reload, etc. -```bash: -# 1. Clone the repo you want to work on -- in this example, it's dev -git clone git@github.com:PurdueEntomologicalResearchCollection/taxonpages-dev.git -cd taxonpages-dev -# 2. Do TaxonPages' funky branch setup -git checkout main -git checkout setup . -# 2. Run locally -npm install -npm run dev -# 3. Make changes -- http://localhost:5173/taxonpages-dev/, edit code, and the app will hot-reload -# 4. Commit changes, being careful to not add foreign objects from the `setup` branch -git add . -# **TODO finish this? Or delete?** -git commit -m "Your message here" +4. Commit and push changes. This is where it gets a little weird, if you haven't worked with multiple repos before. + +```bash +git commit -m "a good description of this commit" +git push dev HEAD:main # push to repository taxonpages-dev's the main branch ``` + +This will [trigger a rebuild](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-dev/actions) in Github Pages, and after a minute or so, the deployed version will be ready to test at https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ + +5. Merge to `deploy-dev`, and Github Actions will build a new version. Be _sure_ you have committed your changes before you do this, because this step will **_erase anything that is not committed_**. + + * The branch `deploy-dev` is the `taxonpages-deploy-dev` repository's `main` branch, if you followed the setup steps above. + * Again, this will [trigger a rebuild, but in the `deploy-dev` repo](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions), but [that version will not work](https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/) because it is configured to run inside Cascade CMS. + +```bash +git reset --hard deploy-dev # Warning: This will totally wipe out any changes you haven't committed. +git merge dev # follow prompts to pull your new changes into the deploy-dev branch +``` + +6. Deploy to Cascade CMS testing page. + + * Download the zip file of artifacts by clicking on the [latest Github Actions workflow run](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions) → **build** → **Upload artifact** → **Artifact download URL** + * Upload the **assets** from that zip file to Cascade CMS, in the appropriate **assets** folder. It should be 4 files — one `.css` and three `.js`. + * In Cascade CMS, edit the HTML to refer to the new files. You will need to edit two filenames: one `.css` and one `.js`. + * Publish your changes. After 10-15 minutes, it will be live on the [PERC Search Test Page](https://ag.purdue.edu/department/agit/test/perc/). + +7. Promote to production, once testing is complete. + + * Merge to the `main` and/or `deploy` branches, similar to above. + * Deploy to the main PERC test page. + * TODO finish details here. + --- # TaxonPages From d5038893875123ac0d72f7c1f1b52e4b1012fcde Mon Sep 17 00:00:00 2001 From: W Beecher Baker Date: Fri, 22 Nov 2024 14:31:47 -0500 Subject: [PATCH 10/10] more development instructions --- README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 67 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 348a8e2..ef626cd 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,9 @@ Each uses GitHub Actions, following [these instructions](https://github.com/Spec ## Local Development -You'll need to clone multiple repos into a _single local git repo_. This may be a new experience, even for seasoned `git` users! +You'll need to [clone multiple repos into a _single local git repo_](https://jigarius.com/blog/multiple-git-remote-repositories). This may be a new experience — even for seasoned developers — but it works very well because it's a core feature of `git`. -1. Clone the production repo, like normal. +1. Clone the production repo, like you would normally. This will become your `origin` remote. ```bash git clone git@github.com:PurdueEntomologicalResearchCollection/taxonpages.git @@ -46,7 +46,7 @@ npm run dev Open http://localhost:5173/taxonpages-dev/ to try it out, see changes hot reload, etc. -4. Commit and push changes. This is where it gets a little weird, if you haven't worked with multiple repos before. +4. Commit and push changes. This push will seem a little weird, if you haven't worked with multiple repos before. ```bash git commit -m "a good description of this commit" @@ -55,28 +55,81 @@ git push dev HEAD:main # push to repository taxonpages-dev's the main branch This will [trigger a rebuild](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-dev/actions) in Github Pages, and after a minute or so, the deployed version will be ready to test at https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/ -5. Merge to `deploy-dev`, and Github Actions will build a new version. Be _sure_ you have committed your changes before you do this, because this step will **_erase anything that is not committed_**. +Congratulations, you have made changes locally and published them to Github Pages! + +## Deploying Changes to Cascade CMS + +After you make changes locally, you'll want to push them up the chain to the [Purdue test page](https://ag.purdue.edu/department/agit/test/perc/) and then to the [production PERC search page](https://ag.purdue.edu/department/entm/perc/search-collection.html). + +1. Tidy up your local branch. Be _sure_ you have committed your changes before you do this, because this step will **_erase anything that is not committed_**. * The branch `deploy-dev` is the `taxonpages-deploy-dev` repository's `main` branch, if you followed the setup steps above. * Again, this will [trigger a rebuild, but in the `deploy-dev` repo](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions), but [that version will not work](https://purdueentomologicalresearchcollection.github.io/taxonpages-dev/) because it is configured to run inside Cascade CMS. ```bash -git reset --hard deploy-dev # Warning: This will totally wipe out any changes you haven't committed. -git merge dev # follow prompts to pull your new changes into the deploy-dev branch +git reset --hard # Warning: This will totally wipe out any changes you haven't committed. ``` -6. Deploy to Cascade CMS testing page. +2. If you haven't already, add two more `git` remotes: - * Download the zip file of artifacts by clicking on the [latest Github Actions workflow run](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions) → **build** → **Upload artifact** → **Artifact download URL** - * Upload the **assets** from that zip file to Cascade CMS, in the appropriate **assets** folder. It should be 4 files — one `.css` and three `.js`. - * In Cascade CMS, edit the HTML to refer to the new files. You will need to edit two filenames: one `.css` and one `.js`. - * Publish your changes. After 10-15 minutes, it will be live on the [PERC Search Test Page](https://ag.purdue.edu/department/agit/test/perc/). +```bash +git checkout -b deploy-setup deploy/setup +git checkout -b deploy-main deploy/main +git checkout -b deploy-dev-setup deploy-dev/setup +git checkout -b deploy-dev-main deploy-dev/main +``` -7. Promote to production, once testing is complete. +3. Deploy to Cascade CMS testing page. + + * First, merge to `deploy-dev`. Github Actions will build a new version, that you can deploy. + +```bash +git checkout deploy-dev +git merge dev # follow prompts to pull your new changes into the deploy-dev branch +``` + + * Download the zip file of artifacts by clicking on the [latest Github Actions workflow run](https://github.com/PurdueEntomologicalResearchCollection/taxonpages-deploy-dev/actions) → **build** → **Upload artifact** → **Artifact download URL** + * Upload the **assets** from that zip file to Cascade CMS, in the appropriate **assets** folder. It should be 4 files — one `.css` and three `.js`. + * In Cascade CMS, edit the HTML to refer to the new files. You will need to edit two filenames: one `.css` and one `.js`. + * Publish your changes. After 10-15 minutes, it will be live on the [PERC Search Test Page](https://ag.purdue.edu/department/agit/test/perc/). + +4. Promote to production, once testing is complete. * Merge to the `main` and/or `deploy` branches, similar to above. - * Deploy to the main PERC test page. - * TODO finish details here. + * See your changes in Github Pages: https://purdueentomologicalresearchcollection.github.io/taxonpages/ + * Deploy to the [main PERC search page](https://ag.purdue.edu/department/entm/perc/search-collection.html). + * **_Voila, site updated!_** + +## Upstream changes + +To keep up with upstream changes — and also to contribute back — you'll need to connect with the [Species File Group](https://speciesfilegroup.org/)'s github repo: https://github.com/SpeciesFileGroup/taxonpages. + +### Catching up with upstream development + +1. Add the remotes (this may be familiar by now) + +```bash +git remote add sfg https://github.com/SpeciesFileGroup/taxonpages.git +git checkout -b sfg-main sfg/main +git checkout -b sfg-setup sfg/setup +``` + +2. Merge upstream changes to your `dev` branch. + +```bash +git checkout dev-main +git merge sfg-main # there will likely be conflicts, homework, npm install, testing, etc — plan for this to take a while +git checkout dev-setup +git merge sfg-setup # probably straightforward? Let's hope. +``` + +3. Test and merge these changes into your other branches, and follow the steps as above for deployment. + +### Contributing upstream + +The pinnacle of open source development: _Contributing back to the community!_ + +This is an advanced topic, and you will need to be in touch with the Species File Group (SFG) developers. The Purdue Entomology faculty and staff can help you get connected. You will [create a pull request](https://github.com/SpeciesFileGroup/taxonpages/compare/main...PurdueEntomologicalResearchCollection:taxonpages:main?expand=1) and review it with SFG developers. ---