From fe376494a9d59ad7a18d75c491f277502a83e7c3 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Thu, 28 Jun 2018 08:58:25 -0700 Subject: [PATCH 1/5] add stub CONTRIBUTING.md --- .github/CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000000..f4898459b3 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,4 @@ +Contributing +============ + +We welcome your contributions! Please see the [contributing](http://pvlib-python.readthedocs.io/en/latest/contributing.html) page for more information about how to contribute. From b0d797eb02ea8333a72254a2a9695773b64232d5 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Thu, 28 Jun 2018 11:50:02 -0700 Subject: [PATCH 2/5] add new contributing guidelines --- .github/PULL_REQUEST_TEMPLATE.md | 18 +++-- docs/sphinx/source/contributing.rst | 106 ++++++++++++++++++++++--- docs/sphinx/source/whatsnew/v0.6.0.rst | 1 + 3 files changed, 104 insertions(+), 21 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7e3cb863b9..238ad49be6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,19 @@ pvlib python pull request guidelines ==================================== -Thank you for your contribution to pvlib python! +Thank you for your contribution to pvlib python! You may delete all of these instructions except for the list below. -You may submit a pull request with your code at any stage of completion, however, before the code can be merged the following items must be addressed: +You may submit a pull request with your code at any stage of completion. - - [ ] Closes issue #xxxx - - [ ] Fully tested. Added and/or modified tests to ensure correct behavior for all reasonable inputs. Tests must pass on the TravisCI and Appveyor testing services. - - [ ] Code quality and style is sufficient. Passes ``git diff upstream/master -u -- "*.py" | flake8 --diff`` and/or landscape.io linting service. - - [ ] New code is fully documented. Includes sphinx/numpydoc compliant docstrings and comments in the code where necessary. +The following items must be addressed before the code can be merged. Please don't hesitate to ask for help if you're unsure of how to accomplish any of the items below: + + - [ ] Closes #xxxx + - [ ] I am familiar with the [contributing guidelines](http://pvlib-python.readthedocs.io/en/latest/contributing.html). + - [ ] Fully tested. Added and/or modified tests to ensure correct behavior for all reasonable inputs. Tests (usually) must pass on the TravisCI and Appveyor testing services. - [ ] Updates entries to `docs/sphinx/source/api.rst` for API changes. - [ ] Adds description and name entries in the appropriate `docs/sphinx/source/whatsnew` file for all changes. - -Please don't hesitate to ask for help if you're unsure of how to accomplish any of the above. You may delete all of these instructions except for the list above. + - [ ] Code quality and style is sufficient. Passes ``git diff upstream/master -u -- "*.py" | flake8 --diff`` + - [ ] New code is fully documented. Includes sphinx/numpydoc compliant docstrings and comments in the code where necessary. + - [ ] Pull request is nearly complete and ready for detailed review. Brief description of the problem and proposed solution (if not already fully described in the issue linked to above): diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 77af3bc4cc..8518cbd496 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -7,6 +7,10 @@ Encouraging more people to help develop pvlib-python is essential to our success. Therefore, we want to make it easy and rewarding for you to contribute. +There is a lot of material in this section, aimed at a variety of +contributors from novice to expert. Don't worry if you don't (yet) +understand parts of it. + Easy ways to contribute ~~~~~~~~~~~~~~~~~~~~~~~ @@ -15,9 +19,13 @@ Here are a few ideas for you can contribute, even if you are new to pvlib-python, git, or Python: * Make `GitHub issues `_ - and contribute to the conversation about how to resolve them. + and contribute to the conversations about how to resolve them. * Read issues and pull requests that other people created and contribute to the conversation about how to resolve them. + Look for issues tagged with + `good first issue `_, + `easy `_, + or `help wanted `_. * Improve the documentation and the unit tests. * Improve the IPython/Jupyter Notebook tutorials or write new ones that demonstrate how to use pvlib-python in your area of expertise. @@ -35,6 +43,9 @@ pvlib-python, git, or Python: How to contribute new code ~~~~~~~~~~~~~~~~~~~~~~~~~~ +The basics +---------- + Contributors to pvlib-python use GitHub's pull requests to add/modify its source code. The GitHub pull request process can be intimidating for new users, but you'll find that it becomes straightforward once you use @@ -53,16 +64,11 @@ process. Here's an outline of the process: request. The Pandas project maintains an excellent `contributing page -`_ that goes into -detail on each of these steps. Also see GitHub's `Set Up Git +`_ that goes +into detail on each of these steps. Also see GitHub's `Set Up Git `_ and `Using Pull Requests `_. -Note that you do not need to make all of your changes before creating a -pull request. Your pull requests will automatically be updated when you -commit new changes and push them to GitHub. This gives everybody an easy -way to comment on the code and can make the process more efficient. - We strongly recommend using virtual environments for development. Virtual environments make it trivial to switch between different versions of software. This `astropy guide @@ -73,11 +79,85 @@ environment. You must include documentation and unit tests for any new or improved code. We can provide help and advice on this after you start the pull -request. +request. See the Testing section below. + + +Pull request scope +------------------ + +This section can be summed up as "less is more". + +A pull request can quickly become unmanageable if too many lines are +added or changed. "Too many" is hard to define, but as a rule of thumb, +we encourage contributions that contain less than 50 lines of primary code. +50 lines of primary code will typically need at least 250 lines +of documentation and testing. A reviewer can typically understand + +A pull request can also quickly become unmanageable if it proposes major +changes to the API. Consider documenting the API changes in +`api.rst `_ +before implementing any code. + +pvlib-python contains 3 "layers" of code: functions, PVSystem/Location, +and ModelChain. We recommend that contributors focus their work on only +one or two of those layers in a single pull request. New models are *not* +required to be available to the higher-level API! + + + +When should I submit a pull request? +------------------------------------ + +The short answer: anytime. + +The long answer: it depends. If in doubt, go ahead and submit. You do +not need to make all of your changes before creating a pull request. +Your pull requests will automatically be updated when you commit new +changes and push them to GitHub. + +There are pros and cons to submitting incomplete pull-requests. On the +plus side, it gives everybody an easy way to comment on the code and can +make the process more efficient. On the minus side, it's easy for an +incomplete pull request to grow into a multi-month saga that leaves +everyone unhappy. If you submit an incomplete pull request, please be +very clear about what you would like feedback on and what we should +ignore. Alternatives to incomplete pull requests include posting a link +to an experimental branch or to a `gist `_ in +the corresponding issue. + +The best way to ensure that a pull request will be reviewed and merged in +a timely manner is to: + +#. Start with an issue. The issue should be well-defined and actionable. +#. Ask the maintainers to tag the issue with the appropriate milestone. +#. Make a limited scope pull request. It can be a lot of work to check all of + the boxes in `pull request guidelines + `_, + especially for pull requests with a lot of new primary code. + See :ref:`Pull request scope`. +#. Tag ``@pvlib/maintainer`` when the pull request is ready for review. + +Questions about related issues frequently come up in the process of +addressing implementing code for a pull request. Please try to avoid +expanding the scope of your pull request. We'd rather see small +additions to the project's technical debt than see a pull request +languish because its scope expanded beyond what the reviewer community +is capable of processing. + + +Code style +~~~~~~~~~~ + +pvlib python uses a mix of full and abbreviated variable names. See +:ref:`_variables_style_rules`. Prefer full names for new contributions. +This is especially important for the API. Abbreviations can be used within +a function to improve the readability of formula. + +Set your editor to strip extra whitespace from line endings. This helps +keep the commit history clean. -The maintainers will follow same procedures, rather than making direct -commits to the main repo. Exceptions may be made for extremely minor -changes, such as fixing documentation typos. +pvlib python does not use logging. Remove any logging calls that you +added during development. Testing @@ -220,5 +300,5 @@ This documentation If this documentation is unclear, help us improve it! Consider looking at the `pandas -documentation `_ for inspiration. diff --git a/docs/sphinx/source/whatsnew/v0.6.0.rst b/docs/sphinx/source/whatsnew/v0.6.0.rst index 5eec801cc4..324aa0e7a4 100644 --- a/docs/sphinx/source/whatsnew/v0.6.0.rst +++ b/docs/sphinx/source/whatsnew/v0.6.0.rst @@ -33,6 +33,7 @@ Documentation objects, and ModelChain. * Updated several incorrect statements in ModelChain documentation regarding implementation status and default values. (:issue:`480`) +* Expanded general contributing and pull request guidelines. Testing From e39cd8ee059607ccfb5c5af7b6a3a89cc8bf8235 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Thu, 28 Jun 2018 13:24:34 -0700 Subject: [PATCH 3/5] clean up errors, typos --- .github/CONTRIBUTING.md | 2 +- docs/sphinx/source/contributing.rst | 49 +++++++++++++++++-------- docs/sphinx/source/package_overview.rst | 6 +-- 3 files changed, 37 insertions(+), 20 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f4898459b3..d1dc84fa5f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,4 +1,4 @@ Contributing ============ -We welcome your contributions! Please see the [contributing](http://pvlib-python.readthedocs.io/en/latest/contributing.html) page for more information about how to contribute. +We welcome your contributions! Please see the [contributing](http://pvlib-python.readthedocs.io/en/latest/contributing.html) page for information about how to contribute. diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 8518cbd496..862a6a76d8 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -82,6 +82,8 @@ code. We can provide help and advice on this after you start the pull request. See the Testing section below. +.. _pull-request-scope: + Pull request scope ------------------ @@ -91,18 +93,26 @@ A pull request can quickly become unmanageable if too many lines are added or changed. "Too many" is hard to define, but as a rule of thumb, we encourage contributions that contain less than 50 lines of primary code. 50 lines of primary code will typically need at least 250 lines -of documentation and testing. A reviewer can typically understand +of documentation and testing. This is about the limit of what the +maintainers can review on a regular basis. -A pull request can also quickly become unmanageable if it proposes major -changes to the API. Consider documenting the API changes in +A pull request can also quickly become unmanageable if it proposes +changes to the API in order to implement another feature. Consider +clearly and concisely documenting all proposed API changes before +implementing any code. Modifying `api.rst `_ -before implementing any code. +and/or the latest `whatsnew file `_ +can help formalize this process. -pvlib-python contains 3 "layers" of code: functions, PVSystem/Location, -and ModelChain. We recommend that contributors focus their work on only -one or two of those layers in a single pull request. New models are *not* -required to be available to the higher-level API! +Of course, sometimes it is necessary to make a large pull request. We +only ask that you take a few minutes to consider how to break it into +smaller chunks before proceeding. +pvlib-python contains :ref:`3 "layers" of code `: +functions, PVSystem/Location, and ModelChain. We recommend that +contributors focus their work on only one or two of those layers in a +single pull request. New models are *not* required to be available to +the higher-level API! When should I submit a pull request? @@ -134,7 +144,7 @@ a timely manner is to: the boxes in `pull request guidelines `_, especially for pull requests with a lot of new primary code. - See :ref:`Pull request scope`. + See :ref:`pull-request-scope`. #. Tag ``@pvlib/maintainer`` when the pull request is ready for review. Questions about related issues frequently come up in the process of @@ -148,22 +158,29 @@ is capable of processing. Code style ~~~~~~~~~~ +pvlib python generally follows the `PEP 8 -- Style Guide for Python Code +`_. Maximum line length for code +is 79 characters. + +Documentation must be written in `numpydoc format `_. + pvlib python uses a mix of full and abbreviated variable names. See -:ref:`_variables_style_rules`. Prefer full names for new contributions. -This is especially important for the API. Abbreviations can be used within -a function to improve the readability of formula. +:ref:`variables_style_rules`. We could be better about consistency. +Prefer full names for new contributions. This is especially important +for the API. Abbreviations can be used within a function to improve the +readability of formulae. Set your editor to strip extra whitespace from line endings. This helps keep the commit history clean. -pvlib python does not use logging. Remove any logging calls that you -added during development. +pvlib python does not use ``logging``. Remove any logging calls that you +added during development. ``warning`` is ok. Testing ~~~~~~~ -pvlib's unit tests can easily be run by executing ``py.test`` on the +pvlib's unit tests can easily be run by executing ``pytest`` on the pvlib directory: ``pytest pvlib`` @@ -228,6 +245,7 @@ in fact, happen. Finally, we check that the output of the method call is reasonable. .. code-block:: python + def test_PVSystem_ashraeiam(mocker): # mocker is a pytest-mock object. # mocker.spy adds code to a function to keep track of how it is called @@ -269,6 +287,7 @@ The example below shows how mock can be used to assert that the correct PVSystem method is called through ``ModelChain.run_model``. .. code-block:: python + def test_modelchain_dc_model(mocker): # set up location and system for model chain location = location.Location(32, -111) diff --git a/docs/sphinx/source/package_overview.rst b/docs/sphinx/source/package_overview.rst index 3a245e368d..f8dd897749 100644 --- a/docs/sphinx/source/package_overview.rst +++ b/docs/sphinx/source/package_overview.rst @@ -282,10 +282,8 @@ change something about pvlib, then please make an issue on our How do I contribute? -------------------- -We're so glad you asked! Please see our -`wiki `_ -for information and instructions on how to contribute. -We really appreciate it! +We're so glad you asked! Please see :ref:`Contributing` for information and +instructions on how to contribute. We really appreciate it! Credits From be886c7469426334ccfc485d2704c6093d8cd5af Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Thu, 5 Jul 2018 15:01:39 -0700 Subject: [PATCH 4/5] review feedback --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- docs/sphinx/source/contributing.rst | 102 ++++++++++++++++++++++------ 2 files changed, 83 insertions(+), 21 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 238ad49be6..eb39df06bc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,7 +7,7 @@ You may submit a pull request with your code at any stage of completion. The following items must be addressed before the code can be merged. Please don't hesitate to ask for help if you're unsure of how to accomplish any of the items below: - - [ ] Closes #xxxx + - [ ] Closes issue #xxxx - [ ] I am familiar with the [contributing guidelines](http://pvlib-python.readthedocs.io/en/latest/contributing.html). - [ ] Fully tested. Added and/or modified tests to ensure correct behavior for all reasonable inputs. Tests (usually) must pass on the TravisCI and Appveyor testing services. - [ ] Updates entries to `docs/sphinx/source/api.rst` for API changes. diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 862a6a76d8..732d293744 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -15,9 +15,11 @@ understand parts of it. Easy ways to contribute ~~~~~~~~~~~~~~~~~~~~~~~ -Here are a few ideas for you can contribute, even if you are new to +Here are a few ideas for how you can contribute, even if you are new to pvlib-python, git, or Python: +* Ask and answer `pvlib questions on StackOverflow `_ + and participate in discussions in the `pvlib-python google group `_. * Make `GitHub issues `_ and contribute to the conversations about how to resolve them. * Read issues and pull requests that other people created and @@ -104,6 +106,14 @@ implementing any code. Modifying and/or the latest `whatsnew file `_ can help formalize this process. +Questions about related issues frequently come up in the process of +addressing implementing code for a pull request. Please try to avoid +expanding the scope of your pull request (this also applies to +reviewers!). We'd rather see small, well-documented additions to the +project's technical debt than see a pull request languish because its +scope expanded beyond what the reviewer community is capable of +processing. + Of course, sometimes it is necessary to make a large pull request. We only ask that you take a few minutes to consider how to break it into smaller chunks before proceeding. @@ -131,29 +141,53 @@ make the process more efficient. On the minus side, it's easy for an incomplete pull request to grow into a multi-month saga that leaves everyone unhappy. If you submit an incomplete pull request, please be very clear about what you would like feedback on and what we should -ignore. Alternatives to incomplete pull requests include posting a link -to an experimental branch or to a `gist `_ in -the corresponding issue. +ignore. Alternatives to incomplete pull requests include creating a +`gist `_ or experimental branch and linking to +it in the corresponding issue. The best way to ensure that a pull request will be reviewed and merged in a timely manner is to: -#. Start with an issue. The issue should be well-defined and actionable. +#. Start by creating an issue. The issue should be well-defined and + actionable. #. Ask the maintainers to tag the issue with the appropriate milestone. -#. Make a limited scope pull request. It can be a lot of work to check all of +#. Make a limited-scope pull request. It can be a lot of work to check all of the boxes in `pull request guidelines `_, especially for pull requests with a lot of new primary code. See :ref:`pull-request-scope`. -#. Tag ``@pvlib/maintainer`` when the pull request is ready for review. +#. Tag pvlib community members or ``@pvlib/maintainer`` when the pull + request is ready for review. (see :ref:`pull-request-reviews`) -Questions about related issues frequently come up in the process of -addressing implementing code for a pull request. Please try to avoid -expanding the scope of your pull request. We'd rather see small -additions to the project's technical debt than see a pull request -languish because its scope expanded beyond what the reviewer community -is capable of processing. +.. _pull-request-reviews: + +Pull request reviews +-------------------- + +The pvlib community and maintainers will review your pull request in a +timely fashion. Please "ping" ``@pvlib/maintainer`` if it seems that +your pull request has been forgotten at any point in the pull request +process. + +Keep in mind that the PV modeling community is diverse and each pvlib +community member brings a different perspective when reviewing code. +Some reviewers bring years of expertise in the sub-field that your code +contributes to and will focus on the details of the algorithm. Other +reviewers will be more focused on integrating your code with the rest of +pvlib, ensuring that it is feasible to maintain, that it meets the +:ref:`code style ` guidelines, and that it is +:ref:`comprehensively tested `. Limiting the scope of the pull +request makes it much more likely that all of these reviews can be +conducted and any issues can be resolved in a timely fashion. + +Sometimes it's hard for reviewers to be immediately available, so the +right amount of patience is to be expected. That said, interested +reviewers should do their best to not wait until the last minute to put +in their two cents. + + +.. _code-style: Code style ~~~~~~~~~~ @@ -162,7 +196,15 @@ pvlib python generally follows the `PEP 8 -- Style Guide for Python Code `_. Maximum line length for code is 79 characters. -Documentation must be written in `numpydoc format `_. +Code must be compatible with python 2.7 and 3.4+. + +Documentation must be written in +`numpydoc format `_. +A relatively easy way to test your documentation is to build it on +`readthedocs.org ` by following their +`Import Your Docs `_ +instructions and enabling your branch on the readthedocs +`versions admin page `_. pvlib python uses a mix of full and abbreviated variable names. See :ref:`variables_style_rules`. We could be better about consistency. @@ -170,12 +212,23 @@ Prefer full names for new contributions. This is especially important for the API. Abbreviations can be used within a function to improve the readability of formulae. -Set your editor to strip extra whitespace from line endings. This helps -keep the commit history clean. +Set your editor to strip extra whitespace from line endings. This +prevents the git commit history from becoming cluttered with whitespace +changes. -pvlib python does not use ``logging``. Remove any logging calls that you -added during development. ``warning`` is ok. +We typically use GitHub's +"`squash and merge` _" +feature to merge your pull request into pvlib. GitHub will condense the +commit history of your branch into a single commit when merging into +pvlib-python/master (the commit history on your branch remains +unchanged). Therefore, you are free to make commits that are as big or +small as you'd like while developing your pull request. +Remove any ``logging`` calls and ``print`` statements that you added +during development. ``warning`` is ok. + + +.. _testing: Testing ~~~~~~~ @@ -193,7 +246,16 @@ or, for a single test: ``pytest pvlib/test/test_clearsky.py::test_ineichen_nans`` -Use the ``--pdb`` flag to debug failures and avoid using ``print``. +We suggest using pytest's ``--pdb`` flag to debug test failures rather +than using ``print`` or ``logging`` calls. For example: + +``pytest pvlib --pdb`` + +will drop you into the +`pdb debugger `_ at the +location of a test failure. As described in :ref:`code-style`, pvlib +code does not use ``print`` or ``logging`` calls, and this also applies +to the test suite (with rare exceptions). New unit test code should be placed in the corresponding test module in the pvlib/test directory. @@ -203,7 +265,7 @@ modifications to pvlib. pvlib-python contains 3 "layers" of code: functions, PVSystem/Location, and ModelChain. Contributors will need to add tests that correspond to -the layer that they modify. +the layers that they modify. Functions --------- From 58f95e0a07d68d5c0614e4f91cdb9ef2628bfc8f Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Fri, 6 Jul 2018 15:27:11 -0700 Subject: [PATCH 5/5] add documentation section --- docs/sphinx/source/contributing.rst | 48 +++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 732d293744..2819a20248 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -198,14 +198,6 @@ is 79 characters. Code must be compatible with python 2.7 and 3.4+. -Documentation must be written in -`numpydoc format `_. -A relatively easy way to test your documentation is to build it on -`readthedocs.org ` by following their -`Import Your Docs `_ -instructions and enabling your branch on the readthedocs -`versions admin page `_. - pvlib python uses a mix of full and abbreviated variable names. See :ref:`variables_style_rules`. We could be better about consistency. Prefer full names for new contributions. This is especially important @@ -216,6 +208,12 @@ Set your editor to strip extra whitespace from line endings. This prevents the git commit history from becoming cluttered with whitespace changes. +Please see :ref:`Documentation` for information specific to documentation +style. + +Remove any ``logging`` calls and ``print`` statements that you added +during development. ``warning`` is ok. + We typically use GitHub's "`squash and merge` _" feature to merge your pull request into pvlib. GitHub will condense the @@ -224,9 +222,39 @@ pvlib-python/master (the commit history on your branch remains unchanged). Therefore, you are free to make commits that are as big or small as you'd like while developing your pull request. -Remove any ``logging`` calls and ``print`` statements that you added -during development. ``warning`` is ok. +.. _documentation: + +Documentation +~~~~~~~~~~~~~ + +Documentation must be written in +`numpydoc format `_. + +The numpydoc format includes a specification for the allowable input +types. Python's `duck typing `_ +allows for multiple input types to work for many parameters. pvlib uses +the following generic descriptors as short-hand to indicate which +specific types may be used: + +* dict-like : dict, OrderedDict, pd.Series +* numeric : scalar, np.array, pd.Series. Typically int or float dtype. +* array-like : np.array, pd.Series. Typically int or float dtype. + +Parameters that specify a specific type require that specific input type. + +A relatively easy way to test your documentation is to build it on +`readthedocs.org ` by following their +`Import Your Docs `_ +instructions and enabling your branch on the readthedocs +`versions admin page `_. + +Another option is to install the required dependencies in your virtual/conda +environment. See +`docs/environment.yml `_ +for the latest dependences for building the complete documentation. Some +doc files can be compiled with fewer dependencies, but this is beyond +the scope of this guide. .. _testing: