How to contribute to DesignSafe Use Cases.
Contributor should Fork this DS User Guide repo to their own account. If prompted, select an organziation to create the fork.
| fork the repo |
|---|
 |
| forking in progress |
|---|
 |
The contributor can later add their students as collaborators in the Settings page:
| add collaborators |
|---|
 |
GitHub will create a forked repo in your user account.
Note: The new repo will say it was forked from the original DS-User-Guide.
| the repo fork |
|---|
 |
Navigate to existing use case folder within user-guide/usecases/1. The folders are named after the PI, so find the folder with PI's name to edit your template. If one does not exist, you may create one (e.g. in user-guide/usecases/1 add the_pi_name/usecase.md). Always check you are only editing the PI's use case folder.
| PI use case folder |
|---|
 |
Click on the usecase.md file in the use case folder to Edit your use case.
Note:
- The document is written in plain text.
- The document supports Markdown syntax (extended) (we use MkDocs').
- Avoid HTML (because Markdown is easier to maintain in this repository).
- You can add attributes via python-markdown "Attribute Lists".
- Do not use deprecated HTML e.g.
nameattribute.- Do not use
<b>or<i>unless**or_(or<strong>or<em>) is inadequate.
| to edit document |
|---|
 |
| editing document |
|---|
 |
Once you have completed editing the use case, you save the changes by commiting. Scroll down to the bottom of the page and type a descriptive phrase explaining the changes you have made and click "Commit changes". If you created a fork, these changes will be saved only in that fork and will not be reflected in the DesignSafe-CI/DS-User-Guide repo until you create a Pull Request (PR) (that step is explained later).
| commit your edits |
|---|
 |
-
To add images to the use case, navigate to the use case folder and select the
imgfolder. Ensure that you are in the use case'simg/folder before adding images.the image folder 
to upload image(s) 
-
Select image files (you can select multiple files) and upload. Once the images are added, type a descriptive commit message and click "Commit changes" to add relevant images to the use case's
img/folder.uploading image(s) 
To show the image in the usecase.md file, add syntax like this into the text:
In this case, we added an image called mpm-algorithm.png, which is located in the use case folder img. We can reference it in the text using:
Note: Use a relative path (like
img/mpm-algorithm.png). Do NOT use a full path (likehttps://github.com/DesignSafe-CI/DS-User-Guide/blob/bcd070b/user-guide/docs/usecases/kumar/img/mpm-algorithm.png).
You can use the "Preview" tab to check images and text formatting before commiting your changes.
| previewing addition of image |
|---|
 |
Commit your changes to GitHub with a meaningful message.
| comitting addition of image |
|---|
 |
Before you are ready to make changes to the DesignSafe-CI/DS-User-Guide repo. Make sure your repository on GitHub is up to date with all the changes from the original repo. You can do this by navigating your repo and click on "Fetch upstream". It might say there is nothing new to fetch.
| no upstream changes to fetch |
|---|
 |
If there are any new changes you can fetch and merge.
| fetch upstream changes |
|---|
 |
Once you have completed making changes, you'll now create a Pull Request (PR) to request that your changes be merged to the main DesignSafe Use Case repo. Go to your repo on GitHub (in my case it is https://github.com/wesleyboar/DS-User-Guide). And select "Contribute". Before opening a pull request, verify the page states:
This branch is N commit(s) ahead of DesignSafe-CI master
| begin to open a PR |
|---|
 |
Verify the changes you've made and select "Create pull request".
| verify the changes |
|---|
 |
Complete the title and description of your PR and select "Open pull request".
| create the PR |
|---|
 |
The PR will show all the changes you have made in the "Files changed" tab.
| files changed |
|---|
 |
You can test your changes on your local machine using a command prompt (very few commands).
Note: GitHub preview is an inaccurate representation of what will appear on the site.
- Markdown rendering is less forgiving than Github's e.g.
- Use 4 spaces to indent.
- Add a new line before starting a list.
If you have added a Use Case, add it to the nav in user-guide/mkdocs.yml —
- Use Cases:
- Overview: usecases/overview.md
- Data Analytics:
- Multi-Data Set Image Analysis in Taggit: usecases/haan/usecase-3.md
- ...
- GeoHazard:
- NGL Database: usecases/brandenberg-ngl/usecase.md
- ...
- Seismic:
- Seismic Response of Concrete Walls: usecases/lowes/usecase.md
- ...
- Wind and Storm Surge:
- Field Sensing Wind Events: usecases/pinelli/usecase.md
- ...— so that it will show up on this User Guide.
To add the new use case to "Wind & Storm Surge":
-
Open
/user-guide/mkdocs.yml. -
Find the
nav"Use Cases" hierarchy within "Wind & Storm Surge" category in "Use Cases":nav: - ... - Use Cases: - Overview: ... - Data Analytics: - ... - GeoHazard: - ... - Seismic: - ... - Wind and Storm Surge: - ...
-
Add an entry for the new use case within "Wind & Storm Surge" category in "Use Cases":
- Wind and Storm Surge: - ... + - New Use Case: your-usecase/usecase.mdEdit the new line to point to the new use case.
After a minute or so a preview deployment of your use case will be available on the pull request page. Select the preview link generated by Netlify to view your changes similar to how it would be rendered in the final version. If you want to make some tweaks. If you created a fork repo, visit that fork repo to make changes. As long as the current PR remains open GitHub will automatically pull your changes.
Warning
Image is outdated. But feature is working as of 2025-12-09.
| link to preview of deployment |
|---|
 |
Warning
Image is outdated. But feature is working as of 2025-12-09.
| preview of deployment |
|---|
 |