How to contribute to DesignSafe Use Cases.
The Principal Investigator (PI) 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 PI 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 your use case folder, which is located in the user-guide/docs/usecases folder. The folders are named after the PI, so find the folder with your name to edit your template. Always check you are only editing your use case folder.
| PI use case folder |
|---|
 |
Click on the usecase.md file in your usecase 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 your use case, you save your 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". These changes will be saved only on your repo and will not be reflected in the original DS User Guide repo until you create a Pull Request (PR) (that step is explained later).
| commit your edits |
|---|
 |
-
To add images to your use case, navigate to your use case folder and select the
imgfolder. Ensure that you are in your usecaseimgfolder 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 your folder.
uploading image(s) 
To insert the image in your 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 usingg:
Note: Use a relative path
img/mpm-algorithm.png, do not use a full path (e.g.,https://github.com/DesignSafe-CI/DS-User-Guide/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 original 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 will probably 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.
Preview Deployment — ⚠️ Feature Not Available Yet
Note: This valuable automated feature was in DS_Use_Case_template. It will eventually be added here also.
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. Visit your GitHub repo of the DS Use Case and make changes. As long as the current PR remains open GitHub will automatically pull your changes.
| link to preview of deployment |
|---|
| preview of deployment |
|---|
If you have added a Use Case, include it into one of the existing use case category documents —
| Category | Document |
|---|---|
| API | apiusecases.md |
| Data Analytics | dataanalyticsusecases.md |
| Geohazard | geohazardusecases.md |
| Seismic | seismicusecases.md |
| Wind and Storm Surge | windstormsurgeusecases.md |
— so that it will show up on this User Guide.
To add to dataanalyticsusecases.md (Data Analytics):
-
Find bottommost
{% include-markdown '…' %}e.g.--- <!-- ## Visualization of spatially distributed data --> {% include-markdown 'padgett/usecase_JN_viz.md' %}
Bottommost include may be different since last update.
-
Add an include to your document in the same way:
--- <!-- ## Description of yur use case --> {% include-markdown 'your-usecase/usecase.md' %}
Edit this include to point to your use case.