Skip to content

Latest commit

 

History

History
139 lines (92 loc) · 8.27 KB

CONTRIBUTING.md

File metadata and controls

139 lines (92 loc) · 8.27 KB
Raw

Contributing to MCTK

Hi! Thanks for your interest in contributing to MCTK. You can contribute in many ways, including:

  1. Report Bugs: please follow Reporting Bugs.
  2. Suggest Enhancements: please follow Suggesting Enhancements.
  3. Contribute Code: please follow Contributing Code.
  4. Contribute Documentation: please follow Contributing Documentation.
  5. Contribute Tests: please follow Contributing Tests.
  6. Contribute Examples: please follow Contributing Examples.
  7. Contribute Artwork: please follow Contributing Artwork.
  8. Contribute Translations: please follow Contributing Translations
  9. Share Ideas: If you have any other ideas or feedback, please follow Sharing Ideas.

Reporting Bugs

This section guides you through submitting a bug report for MCTK. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.

Before Submitting a Bug Report

Please check the following list:

  1. Check MCTK Documentation: you might be able to find the cause of the problem and fix things yourself. Most importantly, check the FAQ and the Troubleshooting sections.
  2. Check MCTK Issues: you might be able to find the same or similar report. If you find a report that seems related to yours, please add a comment to the existing report instead of opening a new one.

Submitting a Bug Report

Please follow these steps:

  1. Open a New Issue: open a new issue on MCTK Issues. Please use the Bug Report template.
  2. Label the Issue: label the issue with the bug label.
  3. Write a Meaningful Title: write a concise, descriptive title. Try to use the same words you would use searching for an existing bug report. Please do not write titles like "Help!" or "Urgent!".
  4. Congratulations!: you have successfully contribued a Bug Report to MCTK. We will take a look at your report as soon as possible! Please feel free to add comments or ask questions in your issue.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for MCTK, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.

Before Submitting an Enhancement Suggestion

Please check the following list:

  1. Check MCTK Documentation: you might be able to find the cause of the problem and fix things yourself. Most importantly, check the FAQ and the Troubleshooting sections.
  2. Check MCTK Issues: you might be able to find the same or similar suggestion. If you find a suggestion that seems related to yours, please add a comment to the existing suggestion instead of opening a new one.

Submitting an Enhancement Suggestion

Please follow these steps:

  1. Open a New Issue: open a new issue on MCTK Issues. Please use the Enhancement Suggestion template.
  2. Label the Issue: label the issue with the enhancement label.
  3. Write a Meaningful Title: write a concise, descriptive title. Try to use the same words you would use searching for an existing enhancement suggestion. Please do not write titles like "Help!" or "Urgent!".
  4. Congratulations!: you have successfully contribued an Enhancement Suggestion to MCTK. We will take a look at your suggestion as soon as possible! Please feel free to add comments or ask questions in your issue.

Contributing Code

This section guides you through contributing code to MCTK. Following these guidelines helps maintainers and the community understand your contribution and find related contributions.

Before Opening a Pull Request

Please follow these steps:

  1. Open a New Issue: open a new issue on MCTK Issues if there is not already an open issue for the code you want to contribute. Please follow the guidelines in Reporting Bugs or Suggesting Enhancements depending on the type of contribution you want to make.

  2. Fork the Repository: fork MCTK Repository to your Github.

  3. Clone your Fork: clone your Fork to your Local Environment.

    git clone https://github.com/[YOUR_USERNAME]/mctk.git

  4. Create a New Branch: create a new branch for the issue you are working on. Please check out MCTK Pull Requests to see the latest available branch number. For example, if MCTK-100 is the last branch that was merged, you should use MCTK-101. It's okay if there exist an open pull request using the same branch number, since the first pull request being merged will own the branch number.

    git checkout -b MCTK-[YOUR_BRANCH_NUMBER]

  5. Check Prerequisites: make sure that you have the following prerequisites:

  6. Install Dependencies: install the all development dependencies for MCTK.

    make develop

  7. Write Code: write code for your changes. You can autoformat your code using the following command:

    make format

  8. Lint Code: lint your code and make sure that there are no errors. You can lint your code using the following command:

    make lint

  9. Write Tests: write tests for your changes. Make sure that all tests pass. You can run all your tests using the following command:

    make test

  10. Increase Coverage: increase the test coverage for your changes. Make sure the coverage hits 100%. You can check the test coverage using the following command:

    make coverage

  11. Commit your Changes: commit your changes to your local repository. It's okay if you have multiple commits for a single pull request, since they will be squashed when merged, but please write meaningful commit messages. Please do not write commit messages like "fix" or "update".

    git commit -m "[YOUR_COMMIT_MESSAGE]"

  12. Push your Changes: push your changes to your fork.

    git push origin MCTK-[YOUR_BRANCH_NUMBER]

Opening a Pull Request

Please follow these steps:

  1. Open a New Pull Request: open a new pull request on MCTK Pull Requests from your fork. Please use the Code Contribution template.

  2. Link Pull Request to the related Issue: link the pull request to the issue you opened in Before Opening a Pull Request.

  3. Label the Pull Request: label the pull request with the labels depending on the type of contribution you made.

  4. Write a Meaningful Title: write a title starting with your Branch Name followed by a colon, a short description, and the Issue Number. You don't need to worry about the Branch Number, since it will be changed when the pull request is merged. For the short description, please follow examples below:

    MCTK-[YOUR_BRANCH_NUMBER]: added feature A for module B, issue #X
MCTK-[YOUR_BRANCH_NUMBER]: fixed bug C for funciton D, issue #Y
MCTK-[YOUR_BRANCH_NUMBER]: updated section E for documentation F, issue #Z

  5. Make sure that all the checks pass: make sure that all the checks pass. If there are any errors, please fix them and push your changes to your fork. The checks will automatically run again.

  6. Congratulations!: you have successfully contributed code to MCTK. We will review your pull request as soon as possible! Please feel free to add comments or ask questions in your pull request.