search

ppb / pursuedpybear

A python game engine.
https://ppb.dev/
Artistic License 2.0
258 stars 98 forks source link

Rewrite README #408

Open pathunstrom opened 4 years ago

pathunstrom commented 4 years ago

With the fact that we already need to modify the README for #407, the maintainers have decided that it's time to focus our messaging.

The README is primarily the entry point for contributors. To that end, we should focus on the needs of contributing users in the README.

Important parts:

  1. A short summary of what the project is.
  2. Instructions for installing in development mode.
  3. The hitchhiker's guide to project layout.
  4. A basic description of the architecture of ppb
  5. Documentation instructions (how to build locally, etc)
  6. How releases work
  7. Project roles, including what counts as a contributor.

If there's anything you think is missing, please comment and I'll update this.

Also, we can discuss in the order they should be in in this ticket.

(I might consider breaking each of these portions into their own ticket but for now, we have this one.)

AstraLuma commented 4 years ago

How does this relate to CONTRIBUTING.md?

pathunstrom commented 4 years ago

Contrinuting.md probably needs to be rewritten, and the README mostly will be summaries and links to the relevant bits.

ProsperousHeart commented 2 years ago

Is this information found anywhere else?

pathunstrom commented 2 years ago
  1. is already in the README, but could use some focus on the README audience (largely contributors)
  2. This might be in the Contributing Guide, but it's mostly "create virtual environment, activate environment, pip install -e ."
  3. This is mostly where the bits live: docs in docs, ppb source in ppb, tests in tests and viztests
  4. This is on me, I'm working on it, but it's a dense document to write. It'll live in the docs once it's finished. Feel free to skip.
  5. This isn't documented directly, but it's the default sphinx set up: install the requirements-docs into your virtual environment, move into the docs folder, the make html to generate locally.
  6. This is documented! https://ppb.readthedocs.io/en/stable/discussion/maintenance-schedules.html#release-schedules
  7. We can skip this, project needs to make a decision on what this looks like. We do treat everyone as a contributor, but the other roles are currently all wrapped up in "maintainer" and probably needs to be fixed long term.