Open bswck opened 9 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.
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.
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.
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.