Merge #375 #404 #406

375: Principles Documentation r=astronouth7303 a=pathunstrom

This is a rough first draft, would love some input on any of these points, or if anyone thinks I'm missing something key.

* [x] Students and Learners First
* [x] Creativity without Limits
* [x] Fun
* [x] Embracing Radical Change

404: v0.8 Docs Pass r=pathunstrom a=astronouth7303

Turns out, the documentation needs a review! Let's fix that up.

406: Update Contributing r=pathunstrom a=astronouth7303

Mostly links

Co-authored-by: Piper Thunstrom <pathunstrom@gmail.com>
Co-authored-by: Jamie Bliss <jamie@ivyleav.es>

CONTRIBUTING.md

@@ -110,7 +110,7 @@ file][tutorial] for more details.
 ## Can I Contribute Without Code?
 
 There's so much else that needs to be done besides fixing `ppb`'s code.
-We need documentation. Docstrings or [the docs project][docs] are
+We need documentation. Docstrings or [the docs folder][docs] are
 available to be added to. Our test suite could use some love. In the
 end you contribute to `ppb` by being part of its community.
 
@@ -119,10 +119,10 @@ end you contribute to `ppb` by being part of its community.
 [contributors]: https://github.com/ppb/pursuedpybear/blob/master/CONTRIBUTORS.md "Contributors"
 [covenant]: http://contributor-covenant.org/ "Contributor's Covenant"
 [discuss]: https://github.com/ppb/pursuedpybear/issues?q=is%3Aissue+is%3Aopen+label%3Adiscussion "PPB Discussions"
-[docs]: https://github.com/ppb/docs "PPB Docs"
+[docs]: https://github.com/ppb/pursuedpybear/tree/master/docs "PPB Docs"
 [draftpr]: https://github.blog/2019-02-14-introducing-draft-pull-requests/ "Introducing draft pull requests"
 [fork]: https://help.github.com/articles/fork-a-repo/ "Fork a repo"
-[goals]: https://github.com/ppb/pursuedpybear#guiding-principles "PPB Goals"
+[goals]: https://ppb.dev/#guiding-principles "PPB Goals"
 [issues]: https://github.com/ppb/pursuedpybear/issues "PPB Issues"
 [new contributor]: https://github.com/ppb/pursuedpybear/labels/new%20contributor "Issues labeld New Contributor"
 [projects]: https://github.com/orgs/ppb/projects "PPB Projects"

README.md

@@ -45,11 +45,10 @@ ppb runs on the latest Python.
 
 ### Object Oriented and Event Driven
 
-`ppb` games are built out of instances of objects that inherit from
-`EventMixin`. Each object only has enough information to respond to the
-event provided, which always includes the current `BaseScene`. Because
-`ppb` doesn't have a master list of events, you can provide new ones
-simply to add more granular control over your game.
+`ppb` games are built out of instances of objects. Each object only has enough
+information to respond to the event provided, which always includes the current
+`BaseScene`. Because `ppb` doesn't have a master list of events, you can
+provide new ones simply to add more granular control over your game.
 
 ### Hardware Library Agnostic
 

docs/discussion/index.rst

@@ -6,7 +6,8 @@ Discussion is a place to talk about the history and why of specific parts of
 advanced users.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Contents:
 
+   values/index
    assets

docs/discussion/values/creativity-without-limits.rst

@@ -0,0 +1,56 @@
+Creativity Without Limits
+==============================
+
+Our focus on creativity without limits is about supporting users at all
+skill levels, and to help guide them from their first lines of code through
+contributing to open source.
+
+From a game perspective, we don't want to discourage any genre of game
+against any other. We don't want to discourage any given scale.
+
+That isn't to mean we don't have some limitations: ``ppb`` is a 2d
+sprite-based engine, it's built in Python, and it is code first.
+
+Code First
+-----------------
+
+The primary reason we want ``ppb`` to be code first is because it allows the
+primary long term limitations set on users is the limitations of the Python
+language itself.
+
+Code first also means that learning ``ppb`` means learning patterns that can be
+applied to other kinds of software. A student who learns with ``ppb``
+shouldn't need to ask "what comes next", the answer should apparent:
+Whatever the next project is that interests them.
+
+No Early Optimization
+------------------------
+
+This is one of those general rules of software development, but it's
+something that creates limitations. If we over optimize our toolset for one
+genre of video game, it adds friction to others. New features should be
+generally applicable or explicitly optional.
+
+The primary example of this is in the basic setup for ppb as a simple event loop
+with the update pattern at its core. This is because it's the most generally
+applicable pattern we have available. We provide a multi-phase update system in
+features for games that need the ability to stage updates instead of
+immediately shifting the state.
+
+Support All Users
+----------------------
+
+We're Students First, but students aren't students forever, and we want
+``ppb`` to grow with them. From their first tutorials through to their first
+shipped video game, and hopefully: to their first open source contribution.
+This is about making sure the resources and community are there to help
+develop ``ppb`` users.
+
+From the user perspective, clear tutorials and example code. Open
+discussions about the design of the system. Type hinting to allow the tools to
+help guide. Progressive revelation of complexity. All of this is meant to guide
+a user from student to pro.
+
+Once they're ready to contribute we care about well defined processes and
+guidelines. A strong description of how documentation is laid out. Where
+code lives and why.

docs/discussion/values/fun.rst

@@ -0,0 +1,39 @@
+Fun
+===================
+
+This one is fairly self evident: Playing games is fun. Making games should be
+fun. And doing both with friends is better.
+
+Delightful to Use
+--------------------------------
+
+One of the core ideas that embedded early in the project is that if some piece of
+``ppb`` wasn't fun to use, we should redo it. Our goal with ppb is a genuinely
+delightful API. Much of this comes from reducing friction in use, but once
+in a while it's about making a change aimed at giving more expressive
+constructions.
+
+One of the changes that we did that demonstrates this is making class
+attributes the default way to initialize state. Combined with a powerful
+``__init__`` it has made rapid prototyping faster and more fun for end users.
+
+Encourage Playful Experimentation
+------------------------------------------
+
+This principle draws from many places: Our student focus, our focus on a
+delightful interface, and the observation that people learn through play. As
+such we have spent a lot of focus on the first few hours of game development.
+From our five minute live demos and various tutorials that are ripe for
+experimentation we want testing ideas to be painless and recovering from a
+misstep to be as inexpensive as possible.
+
+Community Focused
+--------------------------
+
+While ``ppb`` started as a solo project, it's growth has been built on
+community. Decisions are made through discussion and offering ideas is rarely
+discouraged.
+
+Beyond the development of the project, one of our long term focuses is game
+distribution. Part of the fun of making the small games ``ppb`` excel at is
+sharing them with others.

docs/discussion/values/index.rst

@@ -0,0 +1,79 @@
+Principles and Values
+=========================
+
+PursuedPyBear is a principles driven project. From its earliest days, it's been
+guided by a set of ideals that suggest the shape and form of any problem we
+encounter. From our primary focus on students and learners to our embracing
+change of the code and our principles.
+
+We have identified four principles as the root of all the others:
+
+Students and Learners First
+-----------------------------------
+
+Our first commitment is to the new programmers and game makers who have made
+``ppb`` their tool of choice. Whether introduced to them by a teacher or
+discovered on their own, we care about their experiences primarily. However, we
+won't forget educators, professional developers, or hobbyists while doing so.
+Our success is most easily measured by the diversity of our community, and that
+requires a focus on the early stages of use.
+
+Creativity without Limits
+----------------------------------
+
+The only limitation we accept is the limitations that come from the platform
+we've chosen: that being that the only limitation to what you can apply with
+``ppb`` is what the developer is capable of what Python is capable of.
+
+This is why we consider being a code first engine so critical to our design.
+It's one of many reasons we build with Python first.
+
+Fun
+-----------------
+
+We believe tools that are a joy to use are more likely to be picked up for the
+long term. Being fun means more than just joyful discovery. We care that
+complexity is neatly hidden until it's necessary to be addressed. We want to
+reduce "warts" in the API, increase overall discoverability, and allow you to
+work playfully.
+
+Radical Acceptance
+--------------------------------
+
+Over time, the needs of ppb as a project and as a community have changed. It
+started as a solo project to encourage reuse of common patterns in one
+developer's workflows. It's now an education-focused community with a team of
+active developers and a couple dozen contributors. As the needs shift, so too
+do our principles and processes.
+
+By being willing to do hard work and experiment with improvements in code, we've
+been able to build better software. ``ppb`` has seen three major architectures
+since it started. And this document replaces a previous version of our
+principles. Those principles were:
+
+* Education Friendly
+* Idiomatic Python
+* Object Oriented and Event Driven
+* Hardware Library Agnostic
+* Fun
+
+You'll notice that some of them are still with us in this document. Others
+you'll find in the child documents of each of the ones explored here. Some are
+less principles and more design decisions.
+
+In general, we are always willing to field the idea of "maybe we should do it
+this way?" Those questions, even when the answer is no, keep us thinking about
+how things are and how they could be.
+
+Ultimately, ``ppb`` is aspirational as a project, and our principles reflect
+that.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Our Values
+
+   students-first
+   creativity-without-limits
+   fun
+   radical-acceptance

docs/discussion/values/radical-acceptance.rst

@@ -0,0 +1,70 @@
+Radical Acceptance
+===============================
+
+While we do think the greater idea of radical acceptance is important, with
+regard to ppb, radical acceptance is about inclusion, experimentation, and
+willingness to question our assumptions.
+
+
+Accept Significant Change
+-------------------------------
+
+We don't want to be afraid of change. PursuedPyBear is a project about the API,
+and how humans interact with computers changes over times. We shouldn't be
+afraid to abandon API decisions if they stop proving useful.
+
+The "back end" of ``ppb`` has changed significantly on four ocassions so far,
+changing when some limitation was reached. Originally strictly powered by
+dependency injection, we learned that sensible defaults are incredibly
+important. That shifted to a single monolithic API that ran all code directly
+in line. Then we peeled out the first few subsystems. They were still called
+directly, but you could work on them separately from the engine itself. Then we
+moved to the ``Idle`` event and messaging as the way to interact between
+subsystems and the engine itself. In time, even this pattern may prove limiting
+and be changed.
+
+
+Inclusion
+------------------
+
+PursuedPyBear started as the solo project of a trans woman with a non-standard
+education background. As it's grown, we have sought out and encouraged
+contributors from diverse backgrounds. We have a
+`code of conduct <https://ppb.dev/coc.html>`_ that covers all participation in
+the project.
+
+We like being a diverse project, and we will protect the environment that let's
+it be that way.
+
+Education
+++++++++++++++++
+
+While we are a tool for education, we acknowledge that not all learners learn
+the same way. The author was home schooled and self taught software after
+college. Many of the teachers who advise the project come from more traditional
+education backgrounds.
+
+We seek to support learners no matter their education path.
+
+Race
++++++++++++
+
+Similar to education, race should not be an obstacle to using or contributing to
+``ppb``. The maintainers recognize that while that might be a thing we can
+obtain in the project, society is racist and we must work to be anti-racist in
+how we manage the project and community.
+
+Gender
++++++++++++++
+
+The current team of maintainers are all trans feminine. We seek out women and
+gender minorities to contribute to the project. We embrace all genders and hope
+to keep ``ppb`` the kind of community where it is safe to be who you are.
+
+
+Be Willing To Try
+---------------------
+
+When someone is willing to do the work for an idea the rest of the team isn't
+sure about, let them take a chance at it. Usage will tell us if the solution is
+appropriate, not our personal biases.

docs/discussion/values/students-first.rst

@@ -0,0 +1,51 @@
+Student First
+====================
+
+PursuedPyBear is, above all other usages, a tool for learning. We continually
+find ways to reduce the amount of previous knowledge is required to get to your
+first functioning video game. The greatest example of this is the evolution of
+ppb start up throughout time:
+
+Originally, ppb was a strict MVC framework with required dependency injection
+and little concept of sensible defaults. You had to know what each part of the
+system was, instantiate it, and then pass it to the next component.
+
+We kept the dependency injection but rebuilt the engine to have strong opinions
+and defaults at every level of the system. However, you had to know what a
+context manager was, and how to use one.
+
+Today, we can make a functional game in 15 lines of code, and you never need to
+see the underlying context manager.
+
+Progressive Revealing of Complexity
+--------------------------------------------
+
+We want to encourage exploration and flexibility of the underlying tool, and one
+of the ways we achieve this is through only revealing the complexity of the tool
+at the point you must understand it to do something. Our "Hello World!" example
+requires only understanding how to invoke functions and how to write your own:
+the fundamental building blocks of Python programming. In the next hour of
+exploration, it's possible to learn what objects are, how classes are defined
+and using them yourself. And from there, you can begin to learn more complex
+features of Python.
+
+Whenever possible, we prefer to provide powerful and sensible defaults, but with
+as many options for advanced users as possible.
+
+No Apologies
+-------------------------
+
+Every language and tool ends up with a number of quirks known as "wats". In
+``ppb`` we tend to call them "warts": they're places where the knowledge you
+have of how a system works is thrown a curve ball that requires reassessing what
+you know. There are popular wat talks for both Python and Javascript to get a
+feel for what we mean.
+
+One way this bears out is that no matter what level your knowledge of ``ppb``,
+learning something new should only add to that knowledge, not require
+reassessment.
+
+We also try to reduce the number of times a user is forced to ask "why is it
+like this and not like that?" Things that are like messages should use the event
+queue. State should be contained by objects at the right level of abstraction.
+Things should fit the model.

docs/getting-started.rst

@@ -61,6 +61,13 @@ All Systems::
 
    pip install ppb
 
+
+Additionally, on Linux only you must install the SDL library:
+
+Debian, Ubuntu::
+
+   sudo apt install libsdl2-2.0-0 libsdl2-mixer-2.0-0 libsdl2-image-2.0-0 libsdl2-gfx-1.0-0
+
 You should see a few libraries get put together in your terminal, and when
 you have a prompt again, we're ready to go!
 

docs/index.rst

@@ -49,11 +49,10 @@ ppb runs on the latest Python.
 Object Oriented and Event Driven
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``ppb`` games are built out of instances of objects that inherit from
-``EventMixin``. Each object only has enough information to respond to
-the event provided, which always includes the current ``BaseScene``.
-Because ``ppb`` doesn’t have a master list of events, you can provide
-new ones simply to add more granular control over your game.
+``ppb`` games are built out of instances of objects. Each object only has
+enough information to respond to the event provided, which always includes the
+current ``BaseScene``. Because ``ppb`` doesn’t have a master list of events,
+you can provide new ones simply to add more granular control over your game.
 
 Hardware Library Agnostic
 ~~~~~~~~~~~~~~~~~~~~~~~~~