How to Contribute

The Open Modeling Foundation is using GitHub as a platform for members to contribute and modify content. With this platform, we hope to encourage collaboration and accessibility.

You do not need a lot of experience (or any) with Git or GitHub to use this system but this step by step description should help if you find yourself confused. First, you must have a GitHub account to comment or propose changes. If you don’t have an account, you can create one for free at https://github.com/join and additional benefits are available to users affiliated with an academic institution.

There are three ways to contribute to the information presented on this site. You can Discuss this to make a comment or suggestion, note a problem, or start a discussion. For substantive changes, we recommend that you first Create an issue to discuss any proposed changes to the site with the community, and then Suggest edits to submit your proposed changes for review. For minor edits like typos, feel free to simply Suggest edits to fix them.

Adding content to GitHub (discussions and issues) use GitHub's Markdown syntax.

The OMF site itself is built with Hugo so content on our actual pages use Hugo Markdown syntax.

If you would like to be notified about other people’s comments or suggestions, you can Watch this repository by clicking on the Watch button at the upper right corner of the main repository page.

How to Make a Comment or Start a Discussion

1. If you’d like to comment on a given page or start a discussion, click on the Discuss this link at the top right corner of each page.
2. This will open a new tab on our GitHub discussion section with the relevant category already pre-selected (it should be highlighted on the left sidebar with all the categories listed). Discussions for the different Standards and for each working group are grouped by Categories shown in the left sidebar. Discussions for the general Standards Working Group should go into the General category.
3. If you are signed in to GitHub you will be able to begin a new discussion or comment on an existing discussion. To start a new discussion, click on the green New Discussion button located in the upper right corner. This should bring up a form where you can submit your comment using GitHub's Markdown syntax. Be sure to use the select a category menu to choose the appropriate discussion category.
4. When you have finished writing your comment, you can submit it to via the green Start discussion button.

How to create an issue to propose and discuss specific text changes

1. If you would like to propose specific text changes to a page, first click on the Create issue link at the top right corner.
2. This will open up a new tab and take you to our GitHub repository’s issue tracker. If you are not signed into GitHub, you will be prompted to login to GitHub. Once you are signed in you can enter a brief title and description for your issue. If you would like to get the attention of a team member click the @ symbol in the editor for a list of team members. The issue should be automatically labeled based on which section of the site you were viewing.
3. Once you have finished describing your issue, click the green Submit new issue button.
4. You can track the status of your issue on our GitHub issue tracker. You will also be notified via email if someone responds to your issue on GitHub.

How to create a pull request with specific text changes

1. For substantive changes, please create an issue first (described above) and then follow these steps to create a pull request. For minor text changes (e.g., fixing typos, improving clarity / flow / language) feel free to create a pull request without an issue.
2. Navigate to the specific page on the site where you’d like to suggest edits.
3. On that page, click on the Suggest edits link at the top right corner. This will open a new page in a different tab.
4. The first time you attempt to edit a page you will be asked to create a forked repository – do so. (This is your own personal copy of the repository where copies of your proposed edits will be recorded). From time to time you should keep this forked repository up to date
5. You will then be taken to a text editor on the GitHub site where you can make changes. (Note the Preview Changes tab if you want to see the result of your edits)
6. Once you have made all of your changes, scroll down to the “Propose file change” section. In the empty boxes you must include a title and provide a short text description. If the changes you have made are related to an issue that has already been submitted, typing the # will bring up a list of available issues that you can associate with your edits.
7. After those boxes are filled in – click the green Propose file change button.
8. Following this, a comparing changes page will load that shows the original text and your new text changes. To make these changes visible to the site moderators, you must then click the green “Create pull request” button. Please choose Create Draft Pull Request for the time being.
9. Representatives from the Open Modeling Foundation will review your changes for inclusion in the public version of the document.
10. You can track the status of your pull request and its proposed changes on the GitHub pull requests tab. You should receive email notifications when the proposed change has received additional comments or questions, been reviewed, or been merged into the main document.

How to Vote on a Pull Request

OMF Members Council Representatives are eligible to vote on proposed changes. For the interim we are using GitHub’s simple thumbs up / thumbs down emojis to record yays or nays on a pull request representing a set of proposed changes.

1. Select the specific pull request you wish to vote on by clicking on its title.
2. The first comment in the Conversation tab is the one where we will be collecting votes. This comment will display the author submitting the pull request on the left side of the banner and a small face 🙂 on the right side of the banner, next to a dropdown with ellipsis ... A menu of potential emoji reactions is available after clicking on 🙂.
3. To vote on a pull request, use the thumbs up 👍 for a yes vote or thumbs down 👎 emoji for a no vote. You can modify your vote by selecting the thumb you wish to remove from the 🙂 reaction menu at the bottom left of the comment.

How to Find a Specific Pull Request

1. All pull requests submitted to the OMF GitHub site can be viewed on the <code>Pull requests</code> tab.
2. By default this page only displays open requests, ordered by the most recent at the top.
3. You can sort and filter the pull requests table by clicking on the table header names (Author, Label, Projects, etc.). For example, clicking on Author will allow you to select pull requests by a specific author. The sort menu lets you sort pull requests chronologically or by the number of comments or reactions.

For more details on creating a pull request refer to GitHub's guide for creating a pull request.