Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
zackw opened this issue May 20, 2024 · 4 comments
Open

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

zackw opened this issue May 20, 2024 · 4 comments
Labels
help wanted We welcome a contributor to work on this issue! thank you in advance! new-content New feature or request pyconus-24 sprintable

Comments

@zackw
Copy link

zackw commented May 20, 2024

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 willingc added the new-content New feature or request label May 29, 2024
@willingc
Copy link
Collaborator

willingc commented May 29, 2024

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

@willingc willingc changed the title You don't need all these non-code things before you can create a package List bare minimum requirements to create a package on the intro page May 29, 2024
@kierisi
Copy link
Contributor

kierisi commented May 31, 2024

@all-contributors add @zackw for review

Copy link
Contributor

@kierisi

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

@lwasser
Copy link
Member

lwasser commented Jun 6, 2024

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?

@lwasser lwasser added help wanted We welcome a contributor to work on this issue! thank you in advance! sprintable labels Jul 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted We welcome a contributor to work on this issue! thank you in advance! new-content New feature or request pyconus-24 sprintable
Development

No branches or pull requests

4 participants