Plasmapy: Documentation needed for how to do code verification and code quality

[Griffintaur]

I couldn't find below-mentioned points either on Github or website.
Documentation missing points :

• How to do verify code changes or play with the code [for developers/contributors]
• How to do verify code quality and follow style guidelines before contributing
• Things to do before you make a pull request
• How/ Where to write the unit test to ensure code coverage.

[lemmatum]

This is very important, thanks for bringing it up @Griffintaur !

Quick answers on these to help whoever writes the PR for this issue:

How to do verify code changes or play for developers / contributors

• Run pytest across all new/modified modules?
  How to do verify code quality and follow style guidelines before contributing
• Ensure all added functionality has corresponding tests. Make these tests as exhaustive as possible. Coveralls/Travis will catch which parts of the code are totally untested once a PR is opened, but this should not be relied on as a measure of how exhaustive the tests are.
• Run autopep8 locally
• Ensure each function/method/class has a descriptive docstring (we should link or display an example)
• The docstring should contain relevant equations written out in LaTeX so that they can be rendered in the docs
• All physics/math functions should have clear references citing where the equations came from

Things to do before you make a pull request

• Run pytest locally across all new/modified modules. Ensure that tests are passing. (It's fine if you're stuck with a failing test to open a PR and request some help, but just try your best to get as many tests passing as possible)
• Note which issue is being addressed in the PR
  How/ Where to write unit test to ensure code coverage.
• Unit tests are written in using pytest and can be run from a console/commandline by doing pytest test_foo.py to run all tests in a specific test module. pytest tests/ for running all tests in a directory, which can be run at top level to run all tests across PlasmaPy. pytest foo.py to run doctests for a non-testing module. Specific tests within a test module can be run by using nodeids, for example pytest test_foo.py::BarClass::BazMethod as descried here.
• Tests should be located in a subdirectory called tests/, which is located in the directory of the corresponding module. Each module should have its own test module named test_MODULENAME.py
• Each independent test (ideally each assert) should be in it's own function/method so that no tests are skipped when a particular test fails
• I don't think we have a standard for organizing tests yet. So far we've been using a mix of class-based tests, fixtures, and parameterization.

[StanczakDominik]

Bloody hell @lemmatum I was just writing a response to this and yours is way more exhaustive :D I'll finish and we can compare viewpoints

[StanczakDominik]

@Griffintaur Thanks for pointing this out! The only way our docs are going to get good is by people actually using them, so I'm really grateful for trying. I'm gonna discuss your points one by one:

How to do verify code changes or play for developers / contributors

If you mean local testing here, that's included: http://docs.plasmapy.org/en/master/development/testing_guide.html . If you mean something else, please elaborate :)

How to do verify code quality and follow style guidelines before contributing

Yeah, that's something we have to improve here. That can probably be worked in along #357 . The docs on this are pretty incomplete, that's totally on us.

Things to do before you make a pull request

Well... the logic we've been favouring is "make a branch at your fork and go, so that you can use the tools provided by us and GitHub, such as automated tests, @pep8speaks, code review, and so on.". Perhaps that should be explicitly mentioned?

How/ Where to write unit test to ensure code coverage.

Well, this would be http://docs.plasmapy.org/en/master/development/testing_guide.html but I think we could add something like:

• write docstring examples to show how your function works for common use cases AND to make a persistent record of the function's behavior between commits (if the behavior changes, you'll know by the doctest outputs changing)
• write full scale tests in a tests subdirectory at the same location as your code. Compare numerical results to known values, provide sources for those.

[lemmatum]

@StanczakDominik :laughing:
I like your list and especially that you provided links to places in the docs that already answer some of these questions. It'll make linking and organizing things easier. I don't see any conflicts between our lists, so it should be easy to just combine all the ideas for great good!

I think I'd also add:

• mention when you are working on an issue by commenting within that issue
• open PRs early so everyone can see what you are working on and can provide feedback
• commit often and use descriptive commit messages
• Add a comment/label to your PR when it is "Ready for Review"

[StanczakDominik]

@lemmatum to your last point:

• Put [WIP] (standing for Work in Progress) in your PR's title while you don't want it merged just yet and you're just looking for feedback.