|
1 | 1 | # Contribution Guide |
2 | 2 |
|
3 | | -Thank you for you cobributions to UncertainSCI! |
| 3 | +Thank you for you contributions to UncertainSCI! We welcome and appreciate and contributions, from reporting a bugs to code contributions. If you wish to contribute, please do so in the following ways. |
4 | 4 |
|
5 | | -If you'd like to make a tutorial, please follow the instructions in the [Tutorial Tutorial](HowToTutorial.html). |
| 5 | +## Community Support |
| 6 | + |
| 7 | +A great way to start contributing to UncertainSCI is to submit and answer questions on our [discussion board]<https://github.com/SCIInstitute/UncertainSCI/discussions>. |
| 8 | + |
| 9 | +Other ways of contacting the communtity are located on our [support page](../user_docs/support.html#support) |
| 10 | + |
| 11 | +## Bugs and Features |
| 12 | + |
| 13 | +We encourage users to report any bugs they find and request any features they'd like as a [GitHub issue]<https://github.com/SCIInstitute/UncertainSCI/issues>. If you would like to tackle any issues, please volunteer by commenting in the issue or [assigning yourself]<https://docs.github.com/en/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users>. |
| 14 | + |
| 15 | + |
| 16 | +## Make a Tutorial |
| 17 | + |
| 18 | +If you have a tutorial you'd like to share, we'd love to have it. We have a [Tutorial Tutorial](HowToTutorial.html) to explain how to make and contribute tutorials. |
| 19 | + |
| 20 | + |
| 21 | +## Contribute Code |
| 22 | + |
| 23 | +We appreciate to code maintenance and development that our community can provide. If you'd like to submit a bug fix, dependency update, or an added feature, please keep in mind the [style guide](#style-guide), create a [fork](#fork-repo) of the UncertainSCI repo, and use a [Pull Request](#pull-requests) to add it to UncertainSCI. |
| 24 | + |
| 25 | +It is best practice to make sure that there is [GitHub issue]<https://github.com/SCIInstitute/UncertainSCI/issues> to describe the required changes to the code, and having these issues documented become more important with the scope of the additions and changes. Possible additions can also be discussed on our [discussion board]<https://github.com/SCIInstitute/UncertainSCI/discussions>. |
| 26 | + |
| 27 | +### Fork Repo |
| 28 | + |
| 29 | +With your own github account, go to the [UncertainSCI Github page](https://github.com/SCIInstitute/UncertainSCI). Click the fork button on the upper right side of the page. It will ask you where to move the fork to, chose your own account. Once the repository is forked, clone it to your local machine with the following command. |
| 30 | + |
| 31 | +``` |
| 32 | +$git clone https://github.com/[yourgithubaccount]/UncertainSCI.git |
| 33 | +``` |
| 34 | + |
| 35 | +After the the code is cloned, navigate to the repository directory and add the upstream path to the original UncertainSCI repository. |
| 36 | + |
| 37 | +``` |
| 38 | +$git remote add upstream https://github.com/SCIInstitute/UncertainSCI.git |
| 39 | +``` |
| 40 | + |
| 41 | +You should be able to see both your and the original repository when you use the command: |
| 42 | + |
| 43 | +``` |
| 44 | +$git remote -v |
| 45 | +``` |
| 46 | + |
| 47 | +The fork is good to go, but you will need to sync the fork occasionally to keep up with the changes in the main repository. To sync your fork, use the following commands: |
| 48 | + |
| 49 | +``` |
| 50 | +$git fetch upstream |
| 51 | +
|
| 52 | +$git checkout master |
| 53 | +
|
| 54 | +$git merge upstream/master |
| 55 | +``` |
| 56 | +You should sync and merge your fork before you start a new module and before you create a pull request. |
| 57 | +It is a good practice to create a new branch in your fork for every module you will be adding. The command to create a new branch is: |
| 58 | + |
| 59 | +``` |
| 60 | +$git checkout -b [branch_name] |
| 61 | +``` |
| 62 | + |
| 63 | +Please see the [Github help page](https://help.github.com) for more information. |
| 64 | + |
| 65 | +### Pull Requests |
| 66 | + |
| 67 | +With the contributions added to a branch on a fork of UncertainSCI, it is ready to create a [pull request]<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>. While this can be done in many ways, the easiest is probably through the web page of the forked repo. When navigating to the main page, it will usually display the a `contribute` button near the top of the page for recently updated branches. This is a shortcut to creating a pull request to the main repo and branch. Alternatively, a pull request can be created from the pull request tab of either the main repo or the fork. Before making a pull request, please make sure that you've tried your best to follow the [style guide](#style-guide), and that the branch is up-to-date with the lastest master branch. Also, please update or add [testing](#testing) as appropriate. |
| 68 | + |
| 69 | +Once the pull request is created, the maintainers of UncertainSCI will assign reviewers who will test and review the code to ensure that it meets the requirements of the style guide and is stable. It is best to limit the size of each pull request to facilitate review, so if there are major new additions, please add a [GitHub issue]<https://github.com/SCIInstitute/UncertainSCI/issues> to track the progress. |
| 70 | + |
| 71 | + |
| 72 | +## Syle Guide |
| 73 | + |
| 74 | +If you are editing code, take a few minutes to look at the code around you and determine its style. Please try to keep the style of new code as similar as possible to unchanged code to avoid jarring inconsistencies in the style. |
| 75 | + |
| 76 | +### Python |
| 77 | + |
| 78 | +- Indentation is 4 spaces per level for consistency with the rest of the code base. This may be revisited in the future. Do not use tabs. |
| 79 | +- Text encoding: UTF-8 is preferred, Latin-1 is acceptable |
| 80 | +- Comparisons: |
| 81 | + - To singletons (e.g. None): use ‘is’ or ‘is not’, never equality operations. |
| 82 | + - To Booleans (True, False): don’t ever compare with True or False (for further explanation, see PEP 8). |
| 83 | +- Prefix class definitions with two blank lines |
| 84 | +- Imports |
| 85 | + - Grouped in order of scope/commonallity |
| 86 | + - Standard library imports |
| 87 | + - Related third party imports |
| 88 | + - Local apps/library specific imports |
| 89 | + - UncertainSCI application imports and local/module imports may be grouped independently. |
| 90 | + - One package per line (with or without multiple function/module/class imports from the package) |
| 91 | +- Avoid extraneous whitespaces |
| 92 | + |
| 93 | +### Demos and Usecases |
| 94 | + |
| 95 | +New demos and usecases are always welcome. Please add self-contained scripts demonstrating core functionality to the [demos folder]<https://github.com/SCIInstitute/UncertainSCI/tree/master/demos>. Demos that require external packages can be located in seperate repos, such as this [UQ BEM heart position usecase]<https://github.com/SCIInstitute/UQExampleBEMHeartPosition> |
| 96 | + |
| 97 | +### Testing |
| 98 | + |
| 99 | +In addition to demos, please add unit testing to new function contributed to UncertainSCI using pytest. Unit test should be placed in the [test folder]<https://github.com/SCIInstitute/UncertainSCI/tree/master/tests>, which contains several tests to use as examples. To run the test, use the command: |
| 100 | + |
| 101 | +``` |
| 102 | +pytest tests |
| 103 | +``` |
| 104 | + |
6 | 105 |
|
7 | | -We will be filling in more directions about how to to contribute. Try to do the best that you can. |
8 | 106 |
|
9 | 107 |
|
0 commit comments