8000 Improve documentation+guidelines on repo-flow, contribution coding flows · Issue #1471 · pyscript/pyscript · GitHub
[go: up one dir, main page]
Skip to content

Improve documentation+guidelines on repo-flow, contribution coding flows #1471

New issue
8000

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

Sign up for GitHub

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

Jump to bottom
Open
fpliger opened this issue May 16, 2023 Discussed in #1470 · 1 comment
Open

Improve documentation+guidelines on repo-flow, contribution coding flows #1471

fpliger opened this issue May 16, 2023 Discussed in #1470 · 1 comment

Comments

@fpliger
Copy link
Contributor
fpliger commented May 16, 2023

Discussed in #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.
@WebReflection
Copy link
Contributor

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 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@WebReflection @fpliger
0