DesignSafe Use Case Template

A Guide to Adding Your Use Case Project

  1. The Principal Investigator (PI) should Fork the DS User Guide repo to their own account. If prompted, select an organziation to create the fork.

    fork the repo
    fork
    forking in progress
    forking

    The PI can later add their students as collaborators in the Settings page:

    add collaborators
    collaborator
  2. 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
    forked-repo
  3. 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
    PI use case folder
  4. Click on the usecase.md file in your usecase folder to Edit your use case.

    Note: The document is written in plain text, but also supports Markdown syntax.

    to edit document
    Edit usecase md
    editing document
    Edited usecase
  5. 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
    commit edits
  6. To add images to your use case, navigate to your use case folder and select the img folder. Ensure that you are in your usecase img folder before adding images.

    the image folder
    img folder
    to upload image(s)
    add image
  7. 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)
    upload image
  8. To insert the image in your usecase.md file, add syntax like this into the text:

    md ![alternate text](image-location.png)

    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:

    md ![MPM Algorithm](img/mpm-algorithm.png)

    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
    preview image

    Commit your changes to GitHub with a meaningful message.

    comitting addition of image
    image commit
  9. 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
    fetch upstream

    If there are any new changes you can fetch and merge.

    fetch upstream changes
    fetch merge
  10. 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
    Open PR

    Verify the changes you've made and select "Create pull request".

    verify the changes
    Verify Diff

    Complete the title and description of your PR and select "Open pull request".

    create the PR
    Create PR

    The PR will show all the changes you have made in the "Files changed" tab.

    files changed
    PR changes
to Preview Deployment — ⚠️ Feature Not Available Yet 11. 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 | | - | | ⚠️ Feature unavailable. Until feature is available, you may view an [outdated image](docs/images/21-pr.png). | | preview of deployment | | - | | ⚠️ Feature unavailable. Until feature is available, you may view an [outdated image](docs/images/22-preview.png). |