Open rocketnova opened 2 months ago
@lorenyu This PR is really close to being fully done, but I would appreciate if you could give a WIP review of this draft so we can get aligned on the high level changes.
This should be a documentation-only PR. The current draft includes changes to template-only-bin
and .github
that I will pull into a separate PR and then I will adjust the documentation in this PR accordingly. That means that the testing instructions in this PR description do not apply.
Also, this PR does not yet incorporate recent PRs that have been merged, so I would also need to merge those changes in and update this documentation.
@lorenyu Also, if it's not clear, the entrypoint to review should be:
Ticket
Changes
Context for reviewers
This PR provides a comprehensive revision for all of the setup documentation, with an emphasis on providing clear and consistent guidance on how to set up a new project with one or more applications. It addresses existing setup and update instructions that are not clear and/or have circular dependencies (e.g. should you set up network first or app first?).
The new documentation uses the same format for all set up documents:
All of the documentation has been revised for basic technical writing best practices (e.g. active voice over passive voice, short clear sentences, define new terms, etc).
Note: this PR does not attempt to address #581.
Testing
Testing setup
Our current scripting process recommends that users curl from the
main
branch of this repo, so the changes in this PR follow that same pattern. That means that testing requires a manual (noted below).rocket/multi-app
)./template-only-bin/download-and-install-app.sh
, replacemain/template-only-bin
withrocket/multi-app/template-only-bin
./template-only-bin/update-template.sh
, replacemain/template-only-bin
withrocket/multi-app/template-only-bin
.Test 1: Install into a project with a single app
Clone the nextjs template into a new directory.
Change into the new project directory
Dog-food the revised documentation in this PR. Start with the main README.md.
main
of the infra template.git commit
after installing and before configuring the infra template, so you can easily verify changes usinggit diff
.Verify that the the full infra set up works as expected.
Screenshot showing a fully configured project
(No gif I created fit under the github file size limit of 10MB) ![CleanShot 2024-05-15 at 18 32 30@2x](https://github.com/navapbc/template-infra/assets/67701/880d50d2-c22f-4e0e-a6ee-8e0786ff44bc)Test 2: Update a project with a single app
Using the
test-one-app
project dir from Test 1, follow the update directions.curl
command, but because that runs the version of the script onmain
without the changes in this PR and you want to test the changes in this PR, instead run the following to update to the latest release version of the template:Read the output and run
git diff
to verify changes.Example output for updating to a branch
![CleanShot 2024-05-16 at 10 05 04@2x](https://github.com/navapbc/template-infra/assets/67701/f1c11c09-719d-4e8c-9bb2-85c99770d1b2)Example output for updating to a tag
![CleanShot 2024-05-16 at 10 07 03@2x](https://github.com/navapbc/template-infra/assets/67701/48066ea3-2606-45b4-80af-ff6b8e1866af)Test 3: Install into a project with multiple apps
Clone the nextjs template into a new directory.
Change into the new project directory
Install the infra template. Run the normal install script to install the latest
main
of the infra template:Run
git commit
to commit the installed infra template.Before continuing with the remaining infra template installation steps, install a second app to the project by following these instructions.
second-app
.curl
command, but because that runs the version of the script onmain
without the changes in this PR and you want to test the changes in this PR, instead run the following to update to the latest release version of the template:Run
git commit
to commit the installed second app.Dog-food the revised documentation in this PR. Start with the main README.md. Make sure to follow the "For exach application" sections!
Verify that the the full infra set up works as expected
Screenshot showing a configured account + network
![CleanShot 2024-05-16 at 11 09 55@2x](https://github.com/navapbc/template-infra/assets/67701/3da3385b-b5cd-47af-a971-54468136b8f8)Screenshot showing the first configured app
Screenshot showing the second configured app
![CleanShot 2024-05-16 at 11 24 13@2x](https://github.com/navapbc/template-infra/assets/67701/2e49ee3f-0224-4836-a335-3db26839a5e2)Test 4: Update a project with multiple apps
Using the
test-multiple-app
project dir from Test 3, follow the update directions.Normally, you would run the
curl
command, but because that runs the version of the script onmain
without the changes in this PR and you want to test the changes in this PR, instead run the following to update to the latest release version of the template:Read the output and run
git diff
to verify changes.Example output for updating to a branch
![CleanShot 2024-05-16 at 11 30 40@2x](https://github.com/navapbc/template-infra/assets/67701/abcba5b8-72b5-41e3-8759-55ffbb56c91c)