Package Next Steps

[nstarman]

In today's dev telecon we discussed https://github.com/astropy/package-template/ and it's future given that there is also Python Packaging Guide. See the telecon notes (included below) for details. In brief, the suggestions are:

1. Add a message to package_template that we are considering a move to the OA template. The message should probably be added to both the README and the cookie-cutter. See add README note about OA guide #520
2. Recommending users to use to Python Packaging Guide while package_template is reorganized. Blocked by:

• Finalize user documentation by filling out "needs writing" placeholders OpenAstronomy/packaging-guide#23

3. Add documentation how to add Astropy infrastructure on top of Python Packaging Guide, so that affiliate packages can still make astropy-compatible packages.
4. Funded project proposal for keeping these steps up-to-date, or ideally making a sub-branch or “astropy method” in the OA package template.

Quoting from the Dev Telecon:

---

Status of the astropy package template: Should it be retired in favor of Python Packaging Guide?
There is much overlap between the OA guide and the package template, so in the long term it might be good not to have both. However, is there feature parity? Is a migration needed? Should we formally deprecate astropy-template and ask people to migrate? Or should we simply not update it any longer? Or maybe keep both because they are different?
MHvK: can we perhaps make a migration guide? And then deprecate the astropy template?
The discussion in the issue is stalled, so it seems good to bring it up here to make a decision or suggestion on how to proceed.

• The package_template does not always reflex the newest and best CI practices, e.g. GH actions. Have to manually update dependent packages.
  • Is there a way to automate this? We’ve done some in package_template, but it has fallen somewhat by the wayside
• What about dependent packages? How to migrate?
• The OpenAstronomy template requires more understanding and work. package_template “just works”
• The OA template doesn’t have the Astropy infrastructure.
• What about moving the package_template to OA and then the Astropy template uses the OA template, adding the Astropy infrastructure stuff
  • How to keep the Astropy one up-to-date? Who does this?
  • Can cookiecutter manage this?
• Next steps:
  • Message in package_template that we are considering a move to OA template
  • Recommending to OA in the meantime
  • Add documentation how to add Astropy infrastructure on top of OA
  • Funded project proposal for keeping these steps up-to-date, or ideally making a sub-branch or “astropy method” in the OA package template.

[weaverba137]

One comment about the Python Packaging Guide: entire top-level sections of the documentation "Needs writing!". Literally: https://packaging-guide.openastronomy.org/en/latest/scripts.html. I would be hesitant to recommend the template until at least all documentation is filled in.

[pllim]

Good point, @weaverba137 ! I opened issue at OpenAstronomy/packaging-guide#23. cc @Cadair

[Cadair]

PRs welcome ;) (you could always just remove the placeholders then you never would have complained 😉 )

[pllim]

just remove the placeholders

As in, completely remove those pages?

[weaverba137]

I think the documentation of command-line scripts is quite important, and should be filled out rather than removed.

[Cadair]

I think the documentation of command-line scripts is quite important, and should be filled out rather than removed.

Not suggesting it isn't.

[pllim]

What about this? https://github.com/scikit-hep/cookie

[pllim]

I merged #520 but the OpenAstronomy needs to find someone to clean up the template documentation over there.

[pllim]

It's been a while since we started this, so I upgraded the "pending deprecation warning" to "deprecation warning" in README. I will also close issues and PRs not related to the transition as won't fix to drive the point across.