From ae5c12132f1ef9e00a3b8e887004685e91d65264 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Thu, 7 Nov 2019 18:49:26 -0500 Subject: [PATCH 1/5] Update standards based on Nov 2019 PyHC meeting This still needs authors/contributors of the revision added, and to be reviewed during one of our telecons. --- standards.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/standards.md b/standards.md index 5def62d..e455fa0 100644 --- a/standards.md +++ b/standards.md @@ -4,14 +4,20 @@ --- -Drafted during the Heliopython Meeting of November 2018. +Drafted during the Python in Heliophysics Community Meeting of November 2018. + +Amended during the Python in Heliophysics Community Meeting of November 2019. --- -Agreed on 10-Dec-2018 by (in alpahbetical order) +Agreed on 10-Dec-2018 by (in alphabetical order) **A. Annex** (JHU), **B. L. Alterman** (Univ. of Michigan), **A. Azari** (Univ. of Michigan), **W. Barnes** (Rice Univ.), **M. Bobra** (Stanford), **B. Cecconi** (Observartoire de Paris), **S. Christe** (NASA GSFC), **J. Coxon** (Univ. of Southampton), **A. DeWolfe** (LASP), **A. Halford** (Aerospace Corporation), **B. Harter** (LASP), **J. Ireland** (NASA GSFC), **J. Jahn** (SwRI), **J. Klenzing** (NASA GSFC), **M. Liu** (SunPy), **J. Mason** (NASA GSFC), **R. McGranaghan** (NASA JPL), **N. Murphy** (CfA), **S. Murray** (Trinity College Dublin), **J. Niehof** (Univ. of New Hampshire), **M.D. Nguyen** (Lomonosov Moscow State Univ.), **R. Panneton** (CU/LASP), **A. Pembroke** (NASA GSFC), **D. Pérez-Suárez** (University College London), **C. Piker** (Univ. of Iowa), **A. Roberts** (NASA GSFC), **D. Ryan** (NASA GSFC), **S. Savage** (NASA GSFC), **J. Smith** (NASA GSFC, Catholic Univ.), **D. Stansby** (Imperial College London), **J. Vandegriff** (JHU/APL), **R. S. Weigel** (George Mason University) +Amended on 05-Nov-2019 by (in alphabetical order) + +**N. Murphy** (CfA), + --- Definitions: @@ -29,12 +35,13 @@ Definitions: 5. **License**: Projects must provide a license. Projects should use permissive licenses for open source scientific software (e.g., the BSD 2-clause, BSD 3-clause, or BSD+Patent licenses). Copyleft licenses such as GPL are not recommended and OSI-approved permissive licenses are recommended. 6. **Version control**: All code must use version control. It is strongly recommended that projects make use of a distributed version control system (e.g., git). 7. **Coding Style**: Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/) and static analysis tools should be used to identify deviations from the basic style recommendations (e.g. pylint, flake8, pycodestyle). -8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form. -9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended. +8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form. +9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System and acceptance testing are also recommended. 10. **Dependencies**: Projects should import the minimum number of packages necessary. Adding new dependencies should be a __considered__ decision. 11. **Python 3**: All packages must be compatible or work towards being compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 is January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)). -12. **Duplication**: Duplication of code and functionality is discouraged. Forking projects into new projects is strongly discouraged. -13. **Collaboration**: Contributions to packages must be encouraged. Packages must provide contribution guidelines and clearly explain when a contribution is not accepted. -14. **Binaries**: Binary files should be added to the package repository only when necessary in order to keep packages as light as possible. Jupyter notebooks can be binary files and should not be committed to the package repository but can be provided in other repositories. -15. **Code of conduct**: Each project must adopt a code of conduct that is compatible with the [Contributor Covenant](https://www.contributor-covenant.org) and make it publicly available. +12. **Deprecation Policy** (in accordance with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)): Each project should support (1) all minor versions of Python released 42 months prior to the project, and at minimum the two latest minor versions; and (2) all minor versions of NumPy released in the 24 months prior to the project, and at minimum the last three minor versions. In ``setup.py``, the ``python_requires`` variable should be set to the minimum supported version of Python. All supported minor versions of Python should be in the test matrix and have binary artifacts built for the release. Minimum Python and NumPy version support should be adjusted upward only on major and minor releases, and never on a patch release. +13. **Duplication**: Duplication of code and functionality is discouraged. Forking projects into new projects is strongly discouraged. +14. **Collaboration**: Contributions to packages must be encouraged. Packages must provide contribution guidelines, and clearly and constructively explain when a contribution is not accepted. +15. **Binaries**: Binary files should be added to the package repository only when necessary in order to keep packages as light as possible. Jupyter notebooks can be binary files and should not be committed to the package repository but can be provided in other repositories. +16. **Code of conduct**: Each project must adopt a code of conduct that is compatible with the [Contributor Covenant](https://www.contributor-covenant.org) and make it publicly available. Each project should have a reporting procedure for reporting violations of the code of conduct and make it publicly available (for a highly detailed example, refer to the [Code of Conduct Response and Enforcement Manual for NumFOCUS](https://numfocus.org/code-of-conduct/response-and-enforcement-events-meetups)). From 046132aab94bd632119ce420fee67afe081b1ea7 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Mon, 6 Jan 2020 11:58:34 -0500 Subject: [PATCH 2/5] Update date of amendments We discussed the amendments from the fall 2019 meeting during a PyHC telecon on 06-Jan-2020, and approved the changes. We still need to update the list of authors of the amendment. One topic of discussion during this telecon was on adoption of NEP 29 (which created a community-wide standard for how long to support older versions of Python and SciPy) by PyHC packages. Stuart Mumford suggested that it be okay for some packages to have stricter standards, and that packages can support older versions of NumPy and Python if they so choose. Michael Hirsch brought up that usage/download statistics from a package that supports Python 3.5+ showed that very few people are using Python 3.5 at the moment (and also that Python 3.5 gives the most trouble for the testing matrix). I brought up that core packages like SunPy should follow the guidelines of NEP 29 most closely, while packages that are currently under development and have few users would be okay in supporting Python 3.7+ or even 3.8+ if the development phase is going to last ~1-2 years. We decided that using "should" leaves open enough leeway for us to accept packages that have different requirements. I forgot to mention that I think that we should follow the same guidelines for Astropy (and ideally packages within PyHC) as we do for NumPy. (These notes are a convolution of what people actually said, and my ability to remember 42 minutes into the past.) --- standards.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/standards.md b/standards.md index e455fa0..5064762 100644 --- a/standards.md +++ b/standards.md @@ -14,7 +14,7 @@ Agreed on 10-Dec-2018 by (in alphabetical order) **A. Annex** (JHU), **B. L. Alterman** (Univ. of Michigan), **A. Azari** (Univ. of Michigan), **W. Barnes** (Rice Univ.), **M. Bobra** (Stanford), **B. Cecconi** (Observartoire de Paris), **S. Christe** (NASA GSFC), **J. Coxon** (Univ. of Southampton), **A. DeWolfe** (LASP), **A. Halford** (Aerospace Corporation), **B. Harter** (LASP), **J. Ireland** (NASA GSFC), **J. Jahn** (SwRI), **J. Klenzing** (NASA GSFC), **M. Liu** (SunPy), **J. Mason** (NASA GSFC), **R. McGranaghan** (NASA JPL), **N. Murphy** (CfA), **S. Murray** (Trinity College Dublin), **J. Niehof** (Univ. of New Hampshire), **M.D. Nguyen** (Lomonosov Moscow State Univ.), **R. Panneton** (CU/LASP), **A. Pembroke** (NASA GSFC), **D. Pérez-Suárez** (University College London), **C. Piker** (Univ. of Iowa), **A. Roberts** (NASA GSFC), **D. Ryan** (NASA GSFC), **S. Savage** (NASA GSFC), **J. Smith** (NASA GSFC, Catholic Univ.), **D. Stansby** (Imperial College London), **J. Vandegriff** (JHU/APL), **R. S. Weigel** (George Mason University) -Amended on 05-Nov-2019 by (in alphabetical order) +Amended on 06-Jan-2020 by (in alphabetical order) **N. Murphy** (CfA), @@ -40,7 +40,6 @@ Definitions: 10. **Dependencies**: Projects should import the minimum number of packages necessary. Adding new dependencies should be a __considered__ decision. 11. **Python 3**: All packages must be compatible or work towards being compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 is January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)). 12. **Deprecation Policy** (in accordance with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)): Each project should support (1) all minor versions of Python released 42 months prior to the project, and at minimum the two latest minor versions; and (2) all minor versions of NumPy released in the 24 months prior to the project, and at minimum the last three minor versions. In ``setup.py``, the ``python_requires`` variable should be set to the minimum supported version of Python. All supported minor versions of Python should be in the test matrix and have binary artifacts built for the release. Minimum Python and NumPy version support should be adjusted upward only on major and minor releases, and never on a patch release. - 13. **Duplication**: Duplication of code and functionality is discouraged. Forking projects into new projects is strongly discouraged. 14. **Collaboration**: Contributions to packages must be encouraged. Packages must provide contribution guidelines, and clearly and constructively explain when a contribution is not accepted. 15. **Binaries**: Binary files should be added to the package repository only when necessary in order to keep packages as light as possible. Jupyter notebooks can be binary files and should not be committed to the package repository but can be provided in other repositories. From 69c74882d12f5269ce5a600f630e83e2fecd0b1d Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Thu, 9 Jan 2020 19:25:57 -0500 Subject: [PATCH 3/5] Recommend that private functions, etc have docstrings too --- standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards.md b/standards.md index 5064762..73edb8a 100644 --- a/standards.md +++ b/standards.md @@ -35,7 +35,7 @@ Definitions: 5. **License**: Projects must provide a license. Projects should use permissive licenses for open source scientific software (e.g., the BSD 2-clause, BSD 3-clause, or BSD+Patent licenses). Copyleft licenses such as GPL are not recommended and OSI-approved permissive licenses are recommended. 6. **Version control**: All code must use version control. It is strongly recommended that projects make use of a distributed version control system (e.g., git). 7. **Coding Style**: Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/) and static analysis tools should be used to identify deviations from the basic style recommendations (e.g. pylint, flake8, pycodestyle). -8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form. +8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Functions, classes, and modules that are not public-facing should generally have docstring to enable developers to maintain them. Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form. 9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System and acceptance testing are also recommended. 10. **Dependencies**: Projects should import the minimum number of packages necessary. Adding new dependencies should be a __considered__ decision. 11. **Python 3**: All packages must be compatible or work towards being compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 is January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)). From a5ac9bef88468454abc9f75306528bf729454dbb Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Thu, 9 Jan 2020 19:28:40 -0500 Subject: [PATCH 4/5] Make Python 3 compatibility a must --- standards.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standards.md b/standards.md index 73edb8a..25cefc8 100644 --- a/standards.md +++ b/standards.md @@ -12,7 +12,7 @@ Amended during the Python in Heliophysics Community Meeting of November 2019. Agreed on 10-Dec-2018 by (in alphabetical order) -**A. Annex** (JHU), **B. L. Alterman** (Univ. of Michigan), **A. Azari** (Univ. of Michigan), **W. Barnes** (Rice Univ.), **M. Bobra** (Stanford), **B. Cecconi** (Observartoire de Paris), **S. Christe** (NASA GSFC), **J. Coxon** (Univ. of Southampton), **A. DeWolfe** (LASP), **A. Halford** (Aerospace Corporation), **B. Harter** (LASP), **J. Ireland** (NASA GSFC), **J. Jahn** (SwRI), **J. Klenzing** (NASA GSFC), **M. Liu** (SunPy), **J. Mason** (NASA GSFC), **R. McGranaghan** (NASA JPL), **N. Murphy** (CfA), **S. Murray** (Trinity College Dublin), **J. Niehof** (Univ. of New Hampshire), **M.D. Nguyen** (Lomonosov Moscow State Univ.), **R. Panneton** (CU/LASP), **A. Pembroke** (NASA GSFC), **D. Pérez-Suárez** (University College London), **C. Piker** (Univ. of Iowa), **A. Roberts** (NASA GSFC), **D. Ryan** (NASA GSFC), **S. Savage** (NASA GSFC), **J. Smith** (NASA GSFC, Catholic Univ.), **D. Stansby** (Imperial College London), **J. Vandegriff** (JHU/APL), **R. S. Weigel** (George Mason University) +**A. Annex** (JHU), **B. L. Alterman** (Univ. of Michigan), **A. Azari** (Univ. of Michigan), **W. Barnes** (Rice Univ.), **M. Bobra** (Stanford), **B. Cecconi** (Observartoire de Paris), **S. Christe** (NASA GSFC), **J. Coxon** (Univ. of Southampton), **A. DeWolfe** (LASP), **A. Halford** (NASA GSFC), **B. Harter** (LASP), **J. Ireland** (NASA GSFC), **J. Jahn** (SwRI), **J. Klenzing** (NASA GSFC), **M. Liu** (SunPy), **J. Mason** (NASA GSFC), **R. McGranaghan** (NASA JPL), **N. Murphy** (CfA), **S. Murray** (Trinity College Dublin), **J. Niehof** (Univ. of New Hampshire), **M.D. Nguyen** (Lomonosov Moscow State Univ.), **R. Panneton** (CU/LASP), **A. Pembroke** (NASA GSFC), **D. Pérez-Suárez** (University College London), **C. Piker** (Univ. of Iowa), **A. Roberts** (NASA GSFC), **D. Ryan** (NASA GSFC), **S. Savage** (NASA GSFC), **J. Smith** (NASA GSFC, Catholic Univ.), **D. Stansby** (Imperial College London), **J. Vandegriff** (JHU/APL), **R. S. Weigel** (George Mason University) Amended on 06-Jan-2020 by (in alphabetical order) @@ -38,7 +38,7 @@ Definitions: 8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Functions, classes, and modules that are not public-facing should generally have docstring to enable developers to maintain them. Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form. 9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System and acceptance testing are also recommended. 10. **Dependencies**: Projects should import the minimum number of packages necessary. Adding new dependencies should be a __considered__ decision. -11. **Python 3**: All packages must be compatible or work towards being compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 is January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)). +11. **Python 3**: All packages must be compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 was January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)). 12. **Deprecation Policy** (in accordance with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)): Each project should support (1) all minor versions of Python released 42 months prior to the project, and at minimum the two latest minor versions; and (2) all minor versions of NumPy released in the 24 months prior to the project, and at minimum the last three minor versions. In ``setup.py``, the ``python_requires`` variable should be set to the minimum supported version of Python. All supported minor versions of Python should be in the test matrix and have binary artifacts built for the release. Minimum Python and NumPy version support should be adjusted upward only on major and minor releases, and never on a patch release. 13. **Duplication**: Duplication of code and functionality is discouraged. Forking projects into new projects is strongly discouraged. 14. **Collaboration**: Contributions to packages must be encouraged. Packages must provide contribution guidelines, and clearly and constructively explain when a contribution is not accepted. From 15a470c93346561ac8a731ed9a0024d204d1eb7e Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Sun, 13 Sep 2020 20:17:49 -0400 Subject: [PATCH 5/5] Update names and affiliations Co-authored-by: Will Barnes --- standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards.md b/standards.md index 25cefc8..28da182 100644 --- a/standards.md +++ b/standards.md @@ -12,7 +12,7 @@ Amended during the Python in Heliophysics Community Meeting of November 2019. Agreed on 10-Dec-2018 by (in alphabetical order) -**A. Annex** (JHU), **B. L. Alterman** (Univ. of Michigan), **A. Azari** (Univ. of Michigan), **W. Barnes** (Rice Univ.), **M. Bobra** (Stanford), **B. Cecconi** (Observartoire de Paris), **S. Christe** (NASA GSFC), **J. Coxon** (Univ. of Southampton), **A. DeWolfe** (LASP), **A. Halford** (NASA GSFC), **B. Harter** (LASP), **J. Ireland** (NASA GSFC), **J. Jahn** (SwRI), **J. Klenzing** (NASA GSFC), **M. Liu** (SunPy), **J. Mason** (NASA GSFC), **R. McGranaghan** (NASA JPL), **N. Murphy** (CfA), **S. Murray** (Trinity College Dublin), **J. Niehof** (Univ. of New Hampshire), **M.D. Nguyen** (Lomonosov Moscow State Univ.), **R. Panneton** (CU/LASP), **A. Pembroke** (NASA GSFC), **D. Pérez-Suárez** (University College London), **C. Piker** (Univ. of Iowa), **A. Roberts** (NASA GSFC), **D. Ryan** (NASA GSFC), **S. Savage** (NASA GSFC), **J. Smith** (NASA GSFC, Catholic Univ.), **D. Stansby** (Imperial College London), **J. Vandegriff** (JHU/APL), **R. S. Weigel** (George Mason University) +**A. Annex** (JHU), **B. L. Alterman** (Univ. of Michigan), **A. Azari** (Univ. of Michigan), **W. Barnes** (NRC Postdoc residing at NRL), **M. Bobra** (Stanford), **B. Cecconi** (Observartoire de Paris), **S. Christe** (NASA GSFC), **J. Coxon** (Univ. of Southampton), **A. DeWolfe** (LASP), **A. Halford** (NASA GSFC), **B. Harter** (LASP), **J. Ireland** (NASA GSFC), **J. Jahn** (SwRI), **J. Klenzing** (NASA GSFC), **M. Liu** (SunPy), **J. Mason** (NASA GSFC), **R. McGranaghan** (NASA JPL), **N. Murphy** (CfA), **S. Murray** (Trinity College Dublin), **J. Niehof** (Univ. of New Hampshire), **M.D. Nguyen** (Lomonosov Moscow State Univ.), **R. Panneton** (CU/LASP), **A. Pembroke** (NASA GSFC), **D. Pérez-Suárez** (University College London), **C. Piker** (Univ. of Iowa), **A. Roberts** (NASA GSFC), **D. Ryan** (NASA GSFC), **S. Savage** (NASA GSFC), **J. Smith** (NASA GSFC, Catholic Univ.), **D. Stansby** (Imperial College London), **J. Vandegriff** (JHU/APL), **R. S. Weigel** (George Mason University) Amended on 06-Jan-2020 by (in alphabetical order)