Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
121 lines (101 loc) · 7.58 KB

CONTRIBUTING.md

File metadata and controls

121 lines (101 loc) · 7.58 KB

Contributing Guidelines

Thank you for investing your time in contributing to our project!

There are two main ways to contribute to the project - submitting issues and submitting fixes/changes/improvements via pull requests.

Submitting issues

Both bug reports and feature requests are welcome. Submit issues here.

  • Search for existing issues to avoid reporting duplicates.
  • When submitting a bug report:
    • Test it against the most recently released version. It might have been already fixed.
    • Include the code that reproduces the problem or attach the link to the repository with the project which fully reproduces the problem.
    • However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently reproduce them.
    • If the bug is in behavior, then explain what behavior you've expected and what you've got.
  • When submitting a feature request:
    • Explain why you need the feature - what's your use-case, what's your domain.
    • Explaining the problem you face is more important than suggesting a solution. Report your problem even if you don't have any proposed solution.
    • If there is an alternative way to do what you need, then show the code of the alternative.

Submitting PRs

We love PRs. Submit PRs here after reading the PR Workflow. However, please keep in mind that maintainers will have to support the resulting code of the project, so do familiarize yourself with the following guidelines.

  • All development (both new features and bug fixes) is performed in the main branch.
    • Base PRs against the main branch.
    • PR should be linked with the issue, excluding minor documentation changes, the addition of unit tests, and fixing typos.
  • If you make any code changes:
  • If you fix a bug:
    • Write the test the reproduces the bug.
    • Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the corresponding test is too hard or otherwise impractical.
    • Follow the style of writing tests that is used in this project: name test classes as xxx_test.py.
  • If you introduce any new public APIs:
    • All new APIs must come with documentation and tests.
    • If you plan API additions, then please start by submitting an issue with the proposed API design to gather community feedback.
    • Contact the maintainers to coordinate any big piece of work in advance via submitting an issue.
  • If you fix documentation:
    • If you plan extensive rewrites/additions to the docs, then please contact the maintainers to coordinate the work in advance.

How to fix an existing issue

  • If you are going to work on the existing issue:
    • Comment on the existing issue if you want to work on it.
    • Wait till it is assigned to you by maintainers.
    • Ensure that the issue not only describes a problem, but also describes a solution that had received a positive feedback. Propose a solution if there isn't any.
  • If you are going to submit your first PR in this project:
    • Find tickets with the label "good first issue" which are not assigned to somebody.
    • Learn the examples module, submit new interesting example or improve documentation for one of them.
  • If you are an experienced developer with good knowledge of Keras/TensorFlow/PyTorch/ONNX framework, find tickets with the label "good second issue", which are not assigned to somebody.
  • If you are ready to participate in library design and in new experiments, find tickets with the label "research".

Development workflow

  1. Checkout the project using Git.
    • New to Git? Get Git here!
    • Clone project git clone https://github.com/NOWUM/EnSysMod.git
    • Navigate into project folder cd EnSysMod
  2. Install all pre requirements for development
    • New to Python? Get Python here!
    • Create environment sh scripts/install.sh
  3. Check if project is fine
    • Run tests sh scripts/test.sh
  4. Open the project in an IDE of your choice
  5. Time to code! Develop your changes
    • Run main sh scripts/run.sh
    • Run tests sh scripts/test.sh
    • Run linting sh scripts/lint.sh
  6. Ready? Commit your changes
    • Create a new Branch git checkout -b <branch-name>
      The Branch should be named like feature/user-guide or fix/background-color.
    • Check changed files git status
    • Add changed files git add <file-name> or all of them using git add .
    • Commit your changes git commit -m "<your message>"
      The Message should describe your changes like Added development workflow guide or Updated development workflow guide. See this guide for more information.
    • Push your changes git push
  7. All finished? Checkout the PR workflow

PR workflow

  1. Contributor build the project locally and run all unit tests and integration tests. (If it's possible on contributor machine...)
  2. Contributor submits the PR if the local build is successful and tests are green.
  3. Reviewer marks the PR with the "Review" label at the start of the review process.
  4. Reviewer leaves the comments or marks the PR with the label "LGTM."
  5. Contributor answers the comments or fixes the proposed PR.
  6. Reviewer marks the PR with the label "LGTM."
  7. Maintainer could suggest merging the main branch to the PR branch a few times due to changes in the main branch.
  8. Maintainer runs TC builds (unit tests and examples as integration tests).
  9. The TC writes the result (passed or not passed) to the PR checks at the bottom of the proposed PR.
  10. If it is possible, maintainers share the details of the failed build with the contributor.
  11. Maintainer merges the PR if all checks are successful and there is no conflict with the master branch.

Release workflow [Maintainer only]

  1. This task is only for Maintainers!
  2. Merge all PRs into main that should be part of next release.
  3. Run sh scripts/release.sh [major|minor|patch] locally.
  4. Check the PR created for your release here.
  5. Check if documentation is still up-to-date. You can push changes to branch release/x.x.x.
  6. Merge PR if everything looks good to you.
  7. Wait CI/CD for creating your release. See the new release here.
  8. Edit the release and click on button + Auto-generate release notes.
  9. 🎉 Done! 🎉

Contacting maintainers

  • If something cannot be done, not convenient, or does not work - submit an issue.
  • To attract attention to the problem or raised question or a new comment, mention @v3lop5.