From 80bca92e6a115782ad6c4839eb7462a435091b96 Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Tue, 6 Aug 2024 10:46:16 -0400 Subject: [PATCH 1/8] initialize contribute readme file --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..5852f44639 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +Initial commit From 7c2b77c040f575d341ae14bbab047a33d59cf51c Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Tue, 6 Aug 2024 13:51:13 -0400 Subject: [PATCH 2/8] outline CONTRIBUTING --- CONTRIBUTING.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5852f44639..af81b8fc3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,27 @@ -Initial commit +## How to contribute to RMG-Py + +#### **Did you find a bug?** + +* ** Example...** + +* For more detailed information on submitting a bug report and creating an issue, visit our [reporting guidelines](https://example.com). + +#### **Did you write code that fixes a bug?** + +* Open a new GitHub pull request with your changes. + +* Make sure the PR clearly describes the problem + solution. If applicable, include the relevant issue. + +#### **Do you want to see a new feature added?** + +* Suggest your change in the Issues tab + +#### **Do you have questions?** + +* Ex. + +#### **Do you want to contribute to the documentation?** + +* Example here... + +RMG Developers \ No newline at end of file From 1e7bff4c9da8a18c2bba370bdffb7c3cf1fa8f54 Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Wed, 7 Aug 2024 17:00:37 -0400 Subject: [PATCH 3/8] add some contributor guidelines --- CONTRIBUTING.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af81b8fc3a..0a260dec64 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,27 +1,45 @@ ## How to contribute to RMG-Py +Thank you for contributing to RMG-Py! Please take a moment to review our guidelines: + #### **Did you find a bug?** * ** Example...** +* Please include in the ISSUES page. + * For more detailed information on submitting a bug report and creating an issue, visit our [reporting guidelines](https://example.com). #### **Did you write code that fixes a bug?** -* Open a new GitHub pull request with your changes. +* Open a new GitHub PR to merge into the main branch. * Make sure the PR clearly describes the problem + solution. If applicable, include the relevant issue. +* Your PR must pass unit tests, regression tests, and code coverage, and receive approval from a reviewer before it can be merged in. + #### **Do you want to see a new feature added?** -* Suggest your change in the Issues tab +* Suggest your change in the Issues tab. #### **Do you have questions?** -* Ex. +* Email us at rmg_dev@mit.edu. #### **Do you want to contribute to the documentation?** * Example here... +### Best practices for PRs: + +* Rebase to the main branch before working, to avoid merge conflicts. + +* Keep PRs small and aim to merge quickly. + +* Submit a PR only when the code is polished and ready for review. Consider opening a draft PR for work in progress that requires collaborator input. + +* For complex, multi-step PRs, consider opening "megathread" PRs pointing to the main branch. Then, create other PRs that merge into the "megathread" PR branch. This helps divide the review process into smaller chunks. + + +Thank you! RMG Developers \ No newline at end of file From bff12763bc3cd4629919549950eb6564f2c7e24f Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Thu, 8 Aug 2024 12:36:26 -0400 Subject: [PATCH 4/8] add wiki information to CONTRIBUTING.md --- CONTRIBUTING.md | 47 ++++++++++++++++++++++++++++++----------------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a260dec64..054088788f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,44 +2,57 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guidelines: -#### **Did you find a bug?** +#### **Did you find a bug? Do you want to see a new feature?** -* ** Example...** - -* Please include in the ISSUES page. +* Please open an Issue to the corresponding repository: + * [RMG-Py](https://github.com/ReactionMechanismGenerator/RMG-Py/issues): For functionality of the RMG and Arkane software packages + * [RMG-database](https://github.com/ReactionMechanismGenerator/RMG-database/issues): For issues related to the data available to RMG + * [RMG-website](https://github.com/ReactionMechanismGenerator/RMG-website/issues): For issues related to the [RMG website](https://rmg.mit.edu) * For more detailed information on submitting a bug report and creating an issue, visit our [reporting guidelines](https://example.com). -#### **Did you write code that fixes a bug?** +#### **Did you write code that fixes a bug, or adds a new feature?** -* Open a new GitHub PR to merge into the main branch. +* Open a new GitHub PR to merge into the main branch. Make sure the PR clearly describes the problem + solution. If applicable, include the relevant issue. -* Make sure the PR clearly describes the problem + solution. If applicable, include the relevant issue. +* Your PR must pass unit tests, regression tests, and code coverage, and receive approval from at least one reviewer before it can be merged in. -* Your PR must pass unit tests, regression tests, and code coverage, and receive approval from a reviewer before it can be merged in. +* If you wrote a new feature, please add unit tests. If it is a significant new feature, please add a regression test. + * First, please create an input file that includes your new feature. Ensure `saveEdgeSpecies` is set to `True` so that the edge model will also be saved to a file. If applicable, include diverse sets of input conditions to test compatibility with other features. + * Generate the reaction mechanism corresponding to the input file. Ensure that the simulation does not take more than 15 minutes maximum. You can reduce simulation times in multiple ways, e.g. by increasing the `toleranceMoveToCore` flag. + * In the `test/regression` folder, create a new folder with a relevant name, and copy the RMG-Py simulation input file in this folder. Include this new folder in your PR. + * In `.github/workflows/CI.yml`, edit the two lists of regression tests in the `Regression Tests - Execution` and `Regression Tests - Compare to Baseline` steps to add the name of your folder. Be sure to follow BASH syntax. -#### **Do you want to see a new feature added?** + > ** Warning ** + > This will __fail__ CI because of directory not found errors. This is because the baseline files used for comparison in the regression tests do not exist yet. Your PR will need to be merged by bypassing branch protection restrictions. -* Suggest your change in the Issues tab. -#### **Do you have questions?** +#### **Do you want to contribute to the documentation?** -* Email us at rmg_dev@mit.edu. +* Documentation is [hosted here](http://reactionmechanismgenerator.github.io/RMG-Py/) using [Sphinx](https://www.sphinx-doc.org/en/master/). -#### **Do you want to contribute to the documentation?** +* The live version of the documentation is hosted on the `gh-pages` branch which is updated upon pushes to the `main` branch of RMG-Py. + +* To add new documentation, create or modify `.rst` (reStructuredText) files under the `documentation` directory. For a primer on how to write `.rst` markup, please [check out the Sphinx documentation.](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) -* Example here... +* Please test the documentation on a local build (e.g., via `make html` in the `documentation` directory) before pushing changes. -### Best practices for PRs: +#### **Do you have questions?** + +* Email us at rmg_dev@mit.edu. + +#### **Best practices for PRs** * Rebase to the main branch before working, to avoid merge conflicts. * Keep PRs small and aim to merge quickly. -* Submit a PR only when the code is polished and ready for review. Consider opening a draft PR for work in progress that requires collaborator input. +* Commits should be specific and as small as required; commit messages should be descriptive and as long as required. Commit messages should explain *why* the change is needed. We recommend following [these guidelines.](https://wiki.openstack.org/wiki/GitCommitMessages) -* For complex, multi-step PRs, consider opening "megathread" PRs pointing to the main branch. Then, create other PRs that merge into the "megathread" PR branch. This helps divide the review process into smaller chunks. +* Submit a PR only when the code is polished and ready for review. Consider opening a draft PR for work in progress that requires collaborator input. +* Please follow the [PEP8 Python style guide.](https://peps.python.org/pep-0008/) Thank you! + RMG Developers \ No newline at end of file From ddd4856e5672b0f8f6fdcac33174008c44e2eee1 Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Thu, 8 Aug 2024 12:38:11 -0400 Subject: [PATCH 5/8] format CONTRIBUTE.md --- CONTRIBUTING.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 054088788f..2b662dff8a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guidelines: -#### **Did you find a bug? Do you want to see a new feature?** +### **Did you find a bug? Do you want to see a new feature?** * Please open an Issue to the corresponding repository: * [RMG-Py](https://github.com/ReactionMechanismGenerator/RMG-Py/issues): For functionality of the RMG and Arkane software packages @@ -11,7 +11,7 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guideli * For more detailed information on submitting a bug report and creating an issue, visit our [reporting guidelines](https://example.com). -#### **Did you write code that fixes a bug, or adds a new feature?** +### **Did you write code that fixes a bug, or adds a new feature?** * Open a new GitHub PR to merge into the main branch. Make sure the PR clearly describes the problem + solution. If applicable, include the relevant issue. @@ -23,11 +23,10 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guideli * In the `test/regression` folder, create a new folder with a relevant name, and copy the RMG-Py simulation input file in this folder. Include this new folder in your PR. * In `.github/workflows/CI.yml`, edit the two lists of regression tests in the `Regression Tests - Execution` and `Regression Tests - Compare to Baseline` steps to add the name of your folder. Be sure to follow BASH syntax. - > ** Warning ** - > This will __fail__ CI because of directory not found errors. This is because the baseline files used for comparison in the regression tests do not exist yet. Your PR will need to be merged by bypassing branch protection restrictions. + * > Warning: This will __fail__ CI because of directory not found errors. This is because the baseline files used for comparison in the regression tests do not exist yet. Your PR will need to be merged by bypassing branch protection restrictions. -#### **Do you want to contribute to the documentation?** +### **Do you want to contribute to the documentation?** * Documentation is [hosted here](http://reactionmechanismgenerator.github.io/RMG-Py/) using [Sphinx](https://www.sphinx-doc.org/en/master/). @@ -37,11 +36,11 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guideli * Please test the documentation on a local build (e.g., via `make html` in the `documentation` directory) before pushing changes. -#### **Do you have questions?** +### **Do you have questions?** * Email us at rmg_dev@mit.edu. -#### **Best practices for PRs** +### **Best practices for PRs** * Rebase to the main branch before working, to avoid merge conflicts. From f6b6a04cdf4a223986cc8477ec8bf8e4a1e3a5ca Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Thu, 8 Aug 2024 12:39:58 -0400 Subject: [PATCH 6/8] further format CONTRIBUTING.md --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b662dff8a..27135edde0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,9 +9,8 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guideli * [RMG-database](https://github.com/ReactionMechanismGenerator/RMG-database/issues): For issues related to the data available to RMG * [RMG-website](https://github.com/ReactionMechanismGenerator/RMG-website/issues): For issues related to the [RMG website](https://rmg.mit.edu) -* For more detailed information on submitting a bug report and creating an issue, visit our [reporting guidelines](https://example.com). -### **Did you write code that fixes a bug, or adds a new feature?** +### **Did you write code that fixes a bug or adds a new feature?** * Open a new GitHub PR to merge into the main branch. Make sure the PR clearly describes the problem + solution. If applicable, include the relevant issue. From a4e2e8bbb518500f48384555f7dea80644982d2e Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Thu, 8 Aug 2024 12:43:26 -0400 Subject: [PATCH 7/8] clarify CONTRIBUTING testing info --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27135edde0..9def443cca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,9 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guideli * Your PR must pass unit tests, regression tests, and code coverage, and receive approval from at least one reviewer before it can be merged in. -* If you wrote a new feature, please add unit tests. If it is a significant new feature, please add a regression test. +* If you wrote a new feature, please [add unit tests](https://github.com/ReactionMechanismGenerator/RMG-Py/tree/main/test/rmgpy). We currently use [pytest](https://docs.pytest.org/en/stable/) for our unit testing. + +* If you wrote a significant new feature, please add a regression test: * First, please create an input file that includes your new feature. Ensure `saveEdgeSpecies` is set to `True` so that the edge model will also be saved to a file. If applicable, include diverse sets of input conditions to test compatibility with other features. * Generate the reaction mechanism corresponding to the input file. Ensure that the simulation does not take more than 15 minutes maximum. You can reduce simulation times in multiple ways, e.g. by increasing the `toleranceMoveToCore` flag. * In the `test/regression` folder, create a new folder with a relevant name, and copy the RMG-Py simulation input file in this folder. Include this new folder in your PR. From c4da77b23a9f3d7184a24c5b4e503e918d6e779d Mon Sep 17 00:00:00 2001 From: jonwzheng Date: Thu, 8 Aug 2024 12:44:58 -0400 Subject: [PATCH 8/8] clarify CONTRIBUTING that .rst changes should go to main branch --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9def443cca..83f07e7ee3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,7 @@ Thank you for contributing to RMG-Py! Please take a moment to review our guideli * The live version of the documentation is hosted on the `gh-pages` branch which is updated upon pushes to the `main` branch of RMG-Py. -* To add new documentation, create or modify `.rst` (reStructuredText) files under the `documentation` directory. For a primer on how to write `.rst` markup, please [check out the Sphinx documentation.](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) +* To add new documentation, create or modify `.rst` (reStructuredText) files under the `documentation` directory and create a PR to push to `main`. For a primer on how to write `.rst` markup, please [check out the Sphinx documentation.](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) * Please test the documentation on a local build (e.g., via `make html` in the `documentation` directory) before pushing changes.