Skip to content

Latest commit

 

History

History
109 lines (74 loc) · 7.15 KB

CONTRIBUTING.md

File metadata and controls

109 lines (74 loc) · 7.15 KB
Raw

Contributing to the CSDMS Workbench

Thank you for contributing to the CSDMS Workbench, an integrated system of software tools for building, coupling, and running models. The CSDMS Workbench consists of the following core elements:

as well as several other supporting software products.

What follows is a set of guidelines for contributing to the CSDMS Workbench. Use your best judgment, and feel free to ask questions at the CSDMS Help Desk.

Contents

  1. Code of Conduct
  2. Bug Reports
  3. Feature Requests
  4. Pull Requests
  5. Credits

Code of Conduct

This project and everyone participating in it is governed by the CSDMS Code of Conduct. By participating, you are expected to uphold this code.

Bug Reports

Bugs are tracked as GitHub issues. A great way to contribute is to send a detailed issue when you encounter a problem.

Before creating an issue, check that you are using the latest version of the particular CSDMS Workbench tool; if not, see if updating fixes your issue.

To submit a good bug report, explain the problem and include additional details to help the maintainers reproduce the problem.

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the steps which reproduce the problem, including as many details as possible.
  • Provide specific examples to demonstrate the steps. Include links to files. If you're providing code samples in the issue, use Markdown code blocks.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior. Explain which behavior you expected to see instead and why.

Include details about your configuration and environment:

  • The name and version of your operating system.
  • Any details about your local setup that might be helpful in troubleshooting.

Finally, please observe the following:

  • Copy/paste text for error messages instead of using screen captures.
  • Use the GitHub issue web interface for discussing issues instead of replying by email.

Here are a few examples of good bug reports:

Feature Requests

Feature requests are also tracked as GitHub issues.

Before creating an issue, check for existing feature requests first. If you find your feature (or one similar to it), comment on that issue. Do not open a duplicate feature request.

In your request:

  • Use a clear and descriptive title for the issue to identify the feature request.
  • Explain in detail how it would work.
  • Be precise about the proposed outcome of the feature and how it relates to existing features. Include implementation details if possible.
  • Keep the scope as narrow as possible to make it easier to implement.

Here are a few examples of good feature requests:

Pull Requests

Pull requests are the mechanism for making changes to a repository.

Before making a pull request, it's best to describe the changes you wish to make with a maintainer by creating an issue, or by commenting on an existing issue. Because there are only a few people maintaining CSDMS projects, unsolicited pull requests may languish.

When you're ready to propose changes, fork the repository and create a topic branch to hold your changes. Then create the pull request.

Some notes on the process:

  • Ensure the pull request description clearly describes the problem and solution. Include any relevant issue numbers.
  • Smaller is better. Submit one pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. Do not refactor or reformat code that is unrelated to your change. It is better to submit many small pull requests rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether.
  • Coordinate bigger changes. For large and non-trivial changes, be sure to open an issue to discuss a strategy with the maintainers. Otherwise, you risk doing a lot of work for nothing!
  • Prioritize understanding over cleverness. Write code clearly and concisely. Remember that source code usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic should be obvious to a reasonably skilled developer.
  • Follow existing coding style and conventions. Keep your code consistent with the style, formatting, and conventions in the rest of the code base. When possible, these will be enforced with a linter and a formatter. Consistency makes it easier to review and modify in the future.
  • Include unit tests. Follow existing patterns for implementing tests. Make sure new and existing tests pass.
  • Promptly address any CI failures. If your pull request fails to build or pass tests, please push another commit to fix it.
  • Add documentation. Document your changes with code doc comments or in existing guides.

Here are a few examples of good pull requests:

Credits

Please feel free to remix this document for your needs. Some of the material included here is based on or inspired by the work of others, including:

We thank them for their efforts to facilitate collaboration in their projects.