Skip to content

Latest commit

 

History

History
164 lines (113 loc) · 9.38 KB

CONTRIBUTING.md

File metadata and controls

164 lines (113 loc) · 9.38 KB

Contributing to psyplot

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to psyplot and its packages, which are hosted on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Table Of Contents

Code of Conduct

What should I know before I get started?

How Can I Contribute?

Styleguides

Code of Conduct

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

What should I know before I get started?

The psyplot framework

psyplot is just the framework that allows interactive data analysis and visualization. Much of the functionality however is implemented by other packages. What package is the correct one for your bug report/feature request, can be determined by the following list

  • psyplot-gui: Everything specific to the graphical user interface
  • psy-view: Everything specific to the psy-view graphical user interface
  • psy-simple: Everything concerning, e.g. the lineplot, plot2d, density or vector plot methods
  • psy-maps: Everything concerning, e.g. the mapplot, mapvector mapcombined plot methods
  • psy-reg: Everything concerning, e.g. the linreg or densityreg plot methods
  • psyplot: Everything concerning the general framework, e.g. data handling, parallel update, etc.

Concerning plot methods, you can simply find out which module implemented it via

import psyplot.project as psy
print(psy.plot.name-of-your-plot-method._plugin)

If you still don't know, where to open the issue, just go for psyplot.

How Can I Contribute?

Reporting Bugs

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

Before creating bug reports, please check existing issues and pull requests as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining how you started psyplot, e.g. which command exactly you used in the terminal, or how you started psyplot otherwise. When listing steps, don't just say what you did, but explain how you did it. For example, did you update via GUI or console and what?
  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets 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 screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem.
  • If the problem is related to your data structure, include a small example how a similar data structure can be generated

Include details about your configuration and environment:

  • Which version of psyplot are you using? You can get the exact version by running psyplot -aV in your terminal, or by starting the psyplot-gui and open Help->Dependencies.
  • What's the name and version of the OS you're using?

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for psyplot, including completely new features and minor improvements to existing functionality.

If you want to change an existing feature, use the change feature template, otherwise fill in the new feature template.

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. After you've determined which repository your enhancement suggestion is related to, create an issue on that repository and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of psyplot which the suggestion is related to.
  • Explain why this enhancement would be useful to most psyplot users.
  • List some other analysis software or applications where this enhancement exists.
  • Specify which version of psyplot you're using. You can get the exact version by running psyplot -aV in your terminal, or by starting the psyplot-gui and open Help->Dependencies.
  • Specify the name and version of the OS you're using.

Pull Requests

  • Fill in the required template
  • Do not include issue numbers in the PR title
  • Include screenshots and animated GIFs in your pull request whenever possible.
  • Document new code based on the Documentation Styleguide
  • End all files with a newline and follow the PEP8, e.g. by using flake8

Adding new examples

You have new examples? Great! If you want to add them to the documentation, please just fork the correct github repository and add a jupyter notebook in the examples directory, together with all the necessary data files.

And we are always happy to help you finalizing incomplete pull requests.

Styleguides

Git Commit Messages

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line (summary) to 72 characters or less
  • Reference issues and pull requests liberally after the first line
  • When only changing documentation, include [ci skip] in the commit title

Documentation Styleguide

Example

@docstrings.get_sections(base='new_function')
def new_function(a=1):
    """Make some cool new feature

    This function implements a cool new feature

    Parameters
    ----------
    a: int
        First parameter

    Returns
    -------
    something awesome
        The result"""
    ...

@docstrings.dedent
def another_new_function(a=1, b=2):
    """Make another cool new feature

    Parameters
    ----------
    %(new_function.parameters)s
    b: int
        Another parameter

    Returns
    -------
    Something even more awesome"""
    ...

Note: This document has been inspired by the contribution guidelines of Atom