pyscript
Improve documentation+guidelines on repo-flow, contribution coding flows
Discussed in https://github.com/pyscript/pyscript/discussions/1470
Originally posted by fpliger May 16, 2023 Our current contributing guidelines are limited and do not cover many important aspects around:
- how users can contribute
- rules in regards to issues, PRs and releases lifecycle
- merging rules
- tagging rules
- code review process
- merging rules
- test coverage
- etc
I know I'm stating the obvious, but we should have them explicitly covered as part of our documentation.
so ... I had a deeper look at that contributing file and here's what I've noticed:
- we now have a proper website with all the docs in place and it's mentioned more than once in the file itself ... why would we maintain 2 different places to help contributors?
- 35% of links at the top of the page are missing ... it looks like we either generated that "table of content" summary automatically but never updated the current state or we just sketched it down without filling all the points ... again, shouldn't we improve the online documentation instead?
- there are tons of paragraphs not listed at the top that cover a lot of details around PyTest ... but we also have PlayWright tests to talk about ... again, shouldn't this be part of the latest online documentation?
- all GitHub related rules are (imho) the same for every single GitHub project ... I don't find describing these particularly useful beacuse:
- we have already a code of conduct
- we already describe how to file a good issue
- we already ask to check out opened PRs
- ... what else any possible contributor would need to know there? we could state that "until CI is green and somebody else approved your PR won't get ever merged" but that, to me, feels like stating the obvious?
I personally think that to resolve this issue we could:
- cleanup broken parts of the table of contents
- add links to current online documentation which is nicer to read, consume, or understand
- reduce the scope of that file by simply linking current live documentation we maintain elsewhere
- port in such live documentation all the missing parts currently present in there but maybe missing live
Does this sound like a plan? I just want this topic to be covered as much as everyone else does but things changed lately and I think having everything in one place would be desirable and easier to reason about for both users and search engines / AI training that would use one page or another to instrument/iunderstand the PyScript project better.
Thanks for any kind of feedback around this topic 🙏
I think this has been addressed already but in case we need to take further actions we should file an issue in docs, not in here: https://docs.pyscript.net/2025.11.1/contributing/
closing as I am doing some cleanup around issues.