jaraco / skeleton

A generic project skeleton for Python projects.
http://blog.jaraco.com/skeleton/
MIT License
120 stars 38 forks source link

Create contributing guide #100

Open bswck opened 9 months ago

bswck commented 9 months ago

Before I read the article about skeleton, I was confused about various files such as *.egg-info etc. not being automatically excluded by .gitignore in one of the downstream skeleton projects, because repo-local .gitignore files are a very common practice nowadays.

Only later I found this https://blog.jaraco.com/skeleton/#ignoring-artifacts.

Making a simple guide for new contributors might be helpful to get them started and prevent from commiting files they don't intend to commit.

jaraco commented 8 months ago

Good idea. I've been thinking about expanding the skeleton docs to include a section on "expectations from the user" or "user guide", part of which would be the ignoring artifacts section. The real trick is going to be how to surface this documentation to users (without complicating the downstream projects). Perhaps the skeleton badge is enough or maybe a CONTRIBUTING.md is in order. Let me know what you're thinking.

webknjaz commented 8 months ago

So some time ago, as I was writing https://ansible-pylibssh.readthedocs.io/en/latest/contributing/guidelines/ and was thinking of how much of that I'm copying over into other projects. I also wanted something similar in the context of sphinxcontrib-towncrier. I had an idea to have a Sphinx extensions that would inject such pages automatically, generating them in-memory. It turned out, though, that Sphinx doesn't allow making up document paths and filters them out if there's no corresponding documents on disk, which is a shame. I've been meaning to contribute this to Sphinx ever since, but never found time... Still, I think that the concept may be quite useful on the larger scale.

jaraco commented 3 weeks ago

In python/cpython#123144, I realized that much of what's needed in a contribution guide is presented in the skeleton guide, and maybe it would make sense, in order to increase visibility, to rename the badge to "contributing" and re-organize the primary guide to be first about contributing and secondarily about maintenance.