From ebcb0805ee9b29a3a95253fdc5d04b195fc13ae8 Mon Sep 17 00:00:00 2001 From: Abby Wheelis <54848919+Abby-Wheelis@users.noreply.github.com> Date: Thu, 16 Nov 2023 14:50:43 -0700 Subject: [PATCH 1/6] Create start_a_project.md this doc will hold instructions to new projects about the automatic config form in particular --- docs/use/start_a_project.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/use/start_a_project.md diff --git a/docs/use/start_a_project.md b/docs/use/start_a_project.md new file mode 100644 index 0000000..546dfc4 --- /dev/null +++ b/docs/use/start_a_project.md @@ -0,0 +1 @@ +# This is a placeholder From fb38cecb6f2b105ba56900dd07f590475351b819 Mon Sep 17 00:00:00 2001 From: Abby Wheelis <54848919+Abby-Wheelis@users.noreply.github.com> Date: Thu, 16 Nov 2023 14:53:29 -0700 Subject: [PATCH 2/6] Create more_custom_auto_config.md this file will hold a guide to developers about future extensions needed to the automatically generated config --- docs/dev/future/more_custom_auto_config.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/dev/future/more_custom_auto_config.md diff --git a/docs/dev/future/more_custom_auto_config.md b/docs/dev/future/more_custom_auto_config.md new file mode 100644 index 0000000..765b0cd --- /dev/null +++ b/docs/dev/future/more_custom_auto_config.md @@ -0,0 +1 @@ +# this is a placeholder From 0ede59f956c97a452274e05ce25fa94c8d7e24f7 Mon Sep 17 00:00:00 2001 From: Abby Wheelis Date: Thu, 16 Nov 2023 15:46:29 -0700 Subject: [PATCH 3/6] detailed guide for those writing a file --- docs/use/start_a_project.md | 50 ++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/use/start_a_project.md b/docs/use/start_a_project.md index 546dfc4..8e2bffd 100644 --- a/docs/use/start_a_project.md +++ b/docs/use/start_a_project.md @@ -1 +1,49 @@ -# This is a placeholder +# Getting Started with an NREL Hosted Deployment of OpenPATH + +The first step is to contact NREL to draw up an agreement, if you have not contacted us yet please reach out to openpath@nrel.gov to get started. We look forward to hearing about how you plan to use OpenPATH! + +## Customizing Your Project + +### Fill Out the Form + +In order to provide you with a deployment suited to your project's specific needs, we use a special JSON file to configure your app. To create that file, please fill out the form: HERE. Please follow all instructions carefully, as this allows the automated workflow to function as intended and your file to be ready faster! + +You will be asked to provide information such as the name of your project, the purpose behind it, project-specific translations, and preferences for app configurations like the onboarding survey, trip labeling, and reminder schemes. It might help to gather the information before beginning to fill out the form. + +### View Issue and Workflow + +After you fill out the form and click submit, you will see a page with a GitHub Issue containing the information that you input into the form. Please save the link to this page, we may need you to provide it to us. If everything went well, you should see a message at the bottom of the page saying that a bot referenced this issue - this means your config file has been created sucessfully! To see the generated pull request, click on "Pull requests" in the toolbar at the top of the page and find the one with the same number as the issue you opened in the title. This Pull Request will add the configuration for your project to our repo. If you're curious, you can see the generated file by clicking "Files changed" in the top of the pull request. + +## Approval and Merge + +Once the file is ready, a developer will check it over and if everything looks good will merge the new file into the repository. + +Please note that any additonal files, like custom label options or surveys, will also need to be submitted before we can get your project completly ready for testing. + +## Something Went Wrong + +If you do not see a message at the end of your issue form from a bot within a few minutes of clicking submit, something probably went wrong with the automatic file generation process. Don't worry! You can edit the issue to fix the issue. The most likely cause is that you did not follow the instructions on the form. To learn more about the problem, click "actions" in the GitHub toolbar at the top of the page, and then click on the one with [Your Project Name], if it has a red X to the left of the name, there was a problem. Click on the Action and look for an idication of the error, this may help you know what to edit in your issue to fix the problem. A green check next to the workflow means everything went smoothly, if you still don't see the bot message please contact us with the link to your issue and we will investigate. + +## How do I Edit After Submitting? + +To edit your form after you submit, from the issue page that showed up when you clicked submit, cli8cke the 3 dots in the right hand corner of the box containing your form, then click edit. The box with your form will now be a text editor. Make updates as needed, ensuring that you keep the formatting intact. The rows starting with "###" are labels from the form, do not change them. + +## Additional Files? + +If you are choosing a more highly custom route, you might have to provide us with additonal files. Please use the files linked in the descriptions of those fields on the form as examples. Since this is slightly more complex than relying on the default options, there are some manual steps involved. You can submit the files using a GitHub pull request. If you are new to GitHub, this is a good [guide on pull requests ](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). If you do create pull requests for additional files, it would help us out if you could link them in a comment in your pull request. + +### Custom Onbarding Survey + +We provide a default onboarding survey, but if your project needs specialized demographic information, you can write your own survey. The best way to do this is to use KoboToolbox to create the survey, then download the files and submit a pull request to add them to our repository. + +### Custom Trip Labels + +We have a default set of trip mode and purpose labels, but you can also choose to provide your own. Maybe your studied context has unicycle as a common form of transportation! Please create a file like the example for a [program](https://github.com/e-mission/nrel-openpath-deploy-configs/blob/main/label_options/example-program-label-options.json) or a [study](https://github.com/e-mission/nrel-openpath-deploy-configs/blob/main/label_options/example-study-label-options.json) and submit it as a pull request. + +### Custom Trip Surveys + +If your data-gathering needs extend beyond travel mode and purpose, you can ask participants to fill out a survey for each trip. Like the onboarding survey, it is best if you create this with KoboToolbox and submit the files with a pull request. If you do this, the dashboard screen will not be avaliable to participants in the app, as it relies too heavily on traditional labels to be insightful without them. + +## Custom Reminder Schemes + +If you want to customize the schedule on which notificiations are sent to participants to open the app and label their trips, or what those notifications say, please indicate your preferences in the appropriate field on the form and a developer will translate that into the appropriate JSON in your config. \ No newline at end of file From 9e46bb77c1082b92f9a9ea94a60e091b35329fa4 Mon Sep 17 00:00:00 2001 From: Abby Wheelis Date: Thu, 16 Nov 2023 16:04:14 -0700 Subject: [PATCH 4/6] edit adding spacing, catching typos, additional thoughts --- docs/use/start_a_project.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/use/start_a_project.md b/docs/use/start_a_project.md index 8e2bffd..bac5a47 100644 --- a/docs/use/start_a_project.md +++ b/docs/use/start_a_project.md @@ -12,7 +12,11 @@ You will be asked to provide information such as the name of your project, the p ### View Issue and Workflow -After you fill out the form and click submit, you will see a page with a GitHub Issue containing the information that you input into the form. Please save the link to this page, we may need you to provide it to us. If everything went well, you should see a message at the bottom of the page saying that a bot referenced this issue - this means your config file has been created sucessfully! To see the generated pull request, click on "Pull requests" in the toolbar at the top of the page and find the one with the same number as the issue you opened in the title. This Pull Request will add the configuration for your project to our repo. If you're curious, you can see the generated file by clicking "Files changed" in the top of the pull request. +After you fill out the form and click submit, you will see a page with a GitHub Issue containing the information that you input into the form. Please save the link to this page, we may need you to provide it to us. + +If everything went well, you should see a message at the bottom of the page saying that a bot referenced this issue - this means your config file has been created sucessfully! + +To see the generated pull request, click on "Pull requests" in the toolbar at the top of the page and find the one with the same number as the issue you opened in the title. This Pull Request will add the configuration for your project to our repo. If you're curious, you can see the generated file by clicking "Files changed" in the top of the pull request. ## Approval and Merge @@ -22,23 +26,33 @@ Please note that any additonal files, like custom label options or surveys, will ## Something Went Wrong -If you do not see a message at the end of your issue form from a bot within a few minutes of clicking submit, something probably went wrong with the automatic file generation process. Don't worry! You can edit the issue to fix the issue. The most likely cause is that you did not follow the instructions on the form. To learn more about the problem, click "actions" in the GitHub toolbar at the top of the page, and then click on the one with [Your Project Name], if it has a red X to the left of the name, there was a problem. Click on the Action and look for an idication of the error, this may help you know what to edit in your issue to fix the problem. A green check next to the workflow means everything went smoothly, if you still don't see the bot message please contact us with the link to your issue and we will investigate. +If you do not see a message at the end of your issue form from a bot within a few minutes of clicking submit, something probably went wrong with the automatic file generation process. + +Don't worry! You can edit the issue to fix the issue. The most likely cause is that you did not follow the instructions on the form. To learn more about the problem, click "actions" in the GitHub toolbar at the top of the page, and then click on the one with [Your Project Name], if it has a red X to the left of the name, there was a problem. Click on the Action and look for an idication of the error, this may help you know what to edit in your issue to fix the problem. + +A green check next to the workflow means everything went smoothly, if you still don't see the bot message please contact us with the link to your issue and we will investigate. ## How do I Edit After Submitting? -To edit your form after you submit, from the issue page that showed up when you clicked submit, cli8cke the 3 dots in the right hand corner of the box containing your form, then click edit. The box with your form will now be a text editor. Make updates as needed, ensuring that you keep the formatting intact. The rows starting with "###" are labels from the form, do not change them. +To edit your form after you submit, from the issue page that showed up when you clicked submit, click the 3 dots in the right hand corner of the box containing your form, then click edit. + +The box with your form will now be a text editor. Make updates as needed, ensuring that you keep the formatting intact. The rows starting with "###" are labels from the form, do not change them. + +When you're done, click "Update Comment" at the bottom right of the box. ## Additional Files? -If you are choosing a more highly custom route, you might have to provide us with additonal files. Please use the files linked in the descriptions of those fields on the form as examples. Since this is slightly more complex than relying on the default options, there are some manual steps involved. You can submit the files using a GitHub pull request. If you are new to GitHub, this is a good [guide on pull requests ](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). If you do create pull requests for additional files, it would help us out if you could link them in a comment in your pull request. +If you are choosing a more highly custom route, you might have to provide us with additonal files. Please use the files linked in the descriptions of those fields on the form as examples. Since this is slightly more complex than relying on the default options, there are some manual steps involved. You can submit the files using a GitHub pull request. If you are new to GitHub, this is a good [guide on pull requests ](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). If you do create pull requests for additional files, it would help us out if you could link them in a comment in your issue. -### Custom Onbarding Survey +### Custom Onboarding Survey We provide a default onboarding survey, but if your project needs specialized demographic information, you can write your own survey. The best way to do this is to use KoboToolbox to create the survey, then download the files and submit a pull request to add them to our repository. ### Custom Trip Labels -We have a default set of trip mode and purpose labels, but you can also choose to provide your own. Maybe your studied context has unicycle as a common form of transportation! Please create a file like the example for a [program](https://github.com/e-mission/nrel-openpath-deploy-configs/blob/main/label_options/example-program-label-options.json) or a [study](https://github.com/e-mission/nrel-openpath-deploy-configs/blob/main/label_options/example-study-label-options.json) and submit it as a pull request. +We have a default set of trip mode and purpose labels, but you can also choose to provide your own. Please create a file like the example for a [program](https://github.com/e-mission/nrel-openpath-deploy-configs/blob/main/label_options/example-program-label-options.json) or a [study](https://github.com/e-mission/nrel-openpath-deploy-configs/blob/main/label_options/example-study-label-options.json) and submit it as a pull request. + +Modes are somewhat complex. The `value` is what's used behind the scenes. For the `baseMode`, you must choose from [those in our code base](https://github.com/e-mission/e-mission-phone/blob/922a62b7c2601f195bfe8df54654986135e99b25/www/js/diary/diaryHelper.ts#L20), these control the icon and color associated with the mode. The `met` or `met_equivalent` relates to the "metabolic equivalent of task" for each mode, you can specify a custom value, or choose an equivalent from [WALKING, BICYCLING, UNKNOWN, or IN_VEHICLE]. Make sure you specify all needed translations, failing to do so could result in poor UI in your version of the app. ### Custom Trip Surveys From 87041637989f5923cb1cd6ca3a33d446397c9b91 Mon Sep 17 00:00:00 2001 From: Abby Wheelis Date: Thu, 16 Nov 2023 16:17:29 -0700 Subject: [PATCH 5/6] short guide to developers --- docs/dev/future/more_custom_auto_config.md | 28 +++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/dev/future/more_custom_auto_config.md b/docs/dev/future/more_custom_auto_config.md index 765b0cd..982b239 100644 --- a/docs/dev/future/more_custom_auto_config.md +++ b/docs/dev/future/more_custom_auto_config.md @@ -1 +1,27 @@ -# this is a placeholder +# Issue Template Form -> Config File PR + +## GitHub Actions + +The config generation process has now been (at least partially) automated through the use of a GitHub workflow. The following steps will occur: + +- partners fill out the issue template "form" +- upon submission of an issue in the `nrel-openpath-deploy-configs` repo, if it is an instance of the form, a worflow is launched to: + - read the issue + - convert it into a JSON file, formatted properly + - submit a pull request or update an existing pull request to create or update the file + +If this workflow executes sucessfully, some configs should be ready to merge immidiately. + +Others may require additional steps like getting surveys uploaded or creating a notification schedule. + +## Guidance before merge + +Obvious things to check for before merging is that it is a known deployment, that there are no missing fields, and than any surveys or custom labels have been provided + +## Changes to the Configs + +As OpenPATH continues to grow, there may be instances where we need to update the configs - this will require updating the automation. + +The issue template is stored in `nrel-openpath-deploy-configs/.github/ISSUE_TEMPLATE/add-new-config.yml`. You can edit that file to add fields to the form. My convention has been to provide the `id` of form fields to match the key in the config JSON file. + +The bulk of processing happens in `nrel-openpath-deploy-configs/.github/actions/convertIssue/parse-issue-body.js`. Update this file to add the new key/value pair where appropriate. From af4c5ac720f05d72940d5dcf9ee1c848a2efd2db Mon Sep 17 00:00:00 2001 From: Abby Wheelis Date: Thu, 16 Nov 2023 16:22:14 -0700 Subject: [PATCH 6/6] adding a link I want to make sure that I check this, I just copied the one from my repo and then changed Abby-Wheelis to e-mission --- docs/use/start_a_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/use/start_a_project.md b/docs/use/start_a_project.md index bac5a47..e08af5a 100644 --- a/docs/use/start_a_project.md +++ b/docs/use/start_a_project.md @@ -6,7 +6,7 @@ The first step is to contact NREL to draw up an agreement, if you have not conta ### Fill Out the Form -In order to provide you with a deployment suited to your project's specific needs, we use a special JSON file to configure your app. To create that file, please fill out the form: HERE. Please follow all instructions carefully, as this allows the automated workflow to function as intended and your file to be ready faster! +In order to provide you with a deployment suited to your project's specific needs, we use a special JSON file to configure your app. To create that file, please fill out the form: [HERE](https://github.com/e-mission/nrel-openpath-deploy-configs/issues/new?assignees=&labels=new+config&projects=&template=add-new-config.yml&title=New+Project+Configuration+-+%5BPROJECT%5D). Please follow all instructions carefully, as this allows the automated workflow to function as intended and your file to be ready faster! You will be asked to provide information such as the name of your project, the purpose behind it, project-specific translations, and preferences for app configurations like the onboarding survey, trip labeling, and reminder schemes. It might help to gather the information before beginning to fill out the form.