search

pyOpenSci / python-package-guide

scientific Python package recommendations & guidance curated by pyOpenSci
https://www.pyopensci.org/python-package-guide/
Other
70 stars 43 forks source link

List bare minimum requirements to create a package on the intro page #276

Open zackw opened 1 month ago

zackw commented 1 month ago

The “A package is more than just code” section of https://www.pyopensci.org/python-package-guide/tutorials/intro.html could make it sound like you need all this stuff before you can create a package. Docs! Tests! CI! Licensing! Issue tracking! Oy gevalt.

Should clarify which pieces are absolutely essential from the get-go (version control, at least one .py file, and a license), which become important almost immediately for any nontrivial program (docs), which become important as your program gets larger (tests), and which become important as your program gains more users and hopefully also more developers (bug tracker, CI).

willingc commented 1 month ago

Hi @zackw. A fair point about listing what are the bare minimum requirements. We could list them in the Learning Objectives block. Personally, I believe that the docs, tests, etc. are important for a successful, reproducible package so I would like to make sure that we continue to encourage these good software development practices for scientist who may be creating their first software package.

Screenshot 2024-05-29 at 2 28 08 PM
kierisi commented 1 month ago

@all-contributors add @zackw for review

allcontributors[bot] commented 1 month ago

@kierisi

I've put up a pull request to add @zackw! :tada:

lwasser commented 3 weeks ago

this is a really good conversation!! and important. one of the things i always worry about @willingc @zackw is this balance between what you need to create a package - just at the most basic level to be able to reuse your code vs the full picture of docs and tests (which to those newer can also seem super daunting).

there is also this reality that if you have a really well developed package - one person maintaining ALL of that well - is hard. the skills for writing really good docs are quite different from the skills needed to write robust tests. my gosh i can work on stravalib infrastructure updates all day - ci, packaging, and docs. But when i work on the code, i'm much slower and need more review from our other maintainer (as an example).

i wonder if there is a middle ground where we

  1. state exactly what Zack is suggesting like - here are the basic things you need just to turn your code into a package and then
  2. we strong encourage you to also have documentation, tests etc. BUT you don't have to do it all at once.

To avoid that firehouse type of effect that could overwhelm someone getting started. Thoughts?