pygameweb 0.0.6
Pygame.org website.
License: BSD

pygame.org website |build-status| |coverage-status|
===================================================

Pieces of the pygame website (https://www.pygame.org/) will be open sourced here.

Strategy is to bring in code one piece at a time, and clean it up as I go.


It's a community website where people can post projects, comment on them,
but also write things in there themselves on wiki pages.


Contributing
============

Please discuss contributions first to avoid disapointment and rework.

Please see `contribution-guide.org <http://www.contribution-guide.org/>`_ and
`Python Code of Conduct <https://www.python.org/psf/codeofconduct/>`_ for
details on what we expect from contributors. Thanks!

The stack is something like: python 3.6, postgresql 9.6, Flask, py.test, sqlalchemy, alembic, gulp, ansible, node.


Quickstart
==========

Set up the required packages::

    python3.6 -m venv anenv
    . ./anenv/bin/activate
    pip install --upgrade pip
    pip install -r requirements.dev.txt
    pip install -e .


For now yuicompressor is needed for css compression::

    brew install yuicompressor node optipng
    apt-get install yui-compressor nodejs optipng


Environment setup
=================

cp example.env .env


Tool setup
==========

See setup.cfg for all tool config (pytest, coverage, etc).



Db setup instructions
=====================

postgresql 9.6

One database for testing, and another one for running the app.

We use alembic for db migrations. http://alembic.readthedocs.org/en/latest/


Set up the postgresql database::

    createdb pygame
    psql pygame -c "CREATE USER pygame WITH PASSWORD 'password';"
    psql pygame -c "GRANT ALL PRIVILEGES ON DATABASE pygame to pygame;"

We also create a database for running tests::

    createdb pygame_test
    psql pygame -c "CREATE USER pygame_test WITH PASSWORD 'password';"
    psql pygame_test -c "GRANT ALL PRIVILEGES ON DATABASE pygame_test to pygame_test;"


To upgrade to latest model changes do::

    alembic upgrade head


When you change a model make an alembic revision::

    alembic revision --autogenerate -m "Added a field for these reasons."

Then you will need to apply the change to your db (and commit the version file)::

    alembic upgrade head


testing with pytest
===================

http://docs.pytest.org/en/latest/

To run all unit tests and functional tests use::

    pytest

To watch for changes and rerun tests::

    ptw

Maybe you just want to test the wiki parts::

    pytest -k wiki


tests/unit/ are for unit tests.
tests/functional/ are for tests which would use flask and db.
tests/conftest.py is for test configuration.
tests/sqlpytestflask.py are some fixtures for db testing.

Unit tests and functional tests are kept separate, because functional tests can take a while longer to run.

We use various fixtures to make writing the tests easier and faster.


Running the webserver locally
=============================

Use an environment variable to configure the database connection (see the
database setup steps above)::

    export APP_DATABASE_URL="postgresql://pygame:password@localhost/pygame"

Configure a directory containing static files::

    export APP_WWW="static/"

The application may need a secure key, but for debugging it's not important
that it's properly random::

    export APP_SECRET_KEY="s3cret-stuff-blah"

Finally, you can enable some Flask debugging machinery (which should be off for
the site in production)::

    export APP_DEBUG=1

Then run::

    pygameweb_front


Templates with jinja2 and bootstrap
===================================

pygameweb/templates/

We use::

    * `Jinja2 <http://jinja.pocoo.org/>`_
    * `Flask-Bootstrap <https://pythonhosted.org/Flask-Bootstrap/basic-usage.html>`_
    * `Bootstrap <http://getbootstrap.com/>`_


Command line tools with click
=============================

We use click and setuptools entry points (in setup.py) for command line tools::

    * `click <http://click.pocoo.org/5/>`_
    * `entry points <https://packaging.python.org/distributing/#entry-points>`_

Note, when you add or change a command line tool, you need to `pip install -e .` again.

If you can, try not to use command line options at all. Have one command do one thing,
and make the defaults good, or use the pygameweb.config.


User login with Flask-security-fork
===================================

pygameweb.user
pygameweb/templates/security

Using::

    * `flask-security-fork <https://flask-security-fork.readthedocs.io/en/latest/quickstart.html>`_


Navigation with flask-nav
=========================

pygameweb.nav
pygameweb.page.models

Using::

    * `flask-nav <http://pythonhosted.org/flask-nav/>`_
    * `flask-bootstrap <https://pythonhosted.org/Flask-Bootstrap/nav.html>`_



Dashboard is an overview
========================

of all sorts of things happening in the pygame worlds around the interwebs.

https://pygame.org/dashboard

It's a 7000px wide webpage offering a summary of what's happening.

Projects people are working on,
videos folks are making,
tweets twits are... tweeting,
questions asked and answered.



To caching things we
====================

use `Flask-Caching <http://pythonhosted.org/Flask-Caching/>`_

pygameweb.cache
pygameweb.news.views


With with a @cache decorator, and/or markup in a template.



.. |build-status| image:: https://travis-ci.org/pygame/pygameweb.svg?branch=master
   :target: https://travis-ci.org/pygame/pygameweb
   :alt: Build status
.. |coverage-status| image:: https://coveralls.io/repos/github/pygame/pygameweb/badge.svg?branch=master
   :target: https://coveralls.io/github/pygame/pygameweb?branch=master
   :alt: Test coverage percentage




Releases
========

Step by step release instructions below.

- Commits to `master` branch do a dev  deploy to pypi.
- Commits to `mastertest` branch do a dev deploy to pypi.
- Commits to a tag do a real deploy to pypi.


Prereleases
-----------

https://packaging.python.org/tutorials/distributing-packages/#pre-release-versioning

Pre releases should be named like this:
```
# pygameweb/__init__.py
__version__ = '0.0.2'
```
Which is one version ahead of of the last tagged release.

Release tags should be like '0.0.2', and match the `pygameweb/__init__.py __version__`.


Preparing a release in a branch.
--------------------------------

It's a good idea to start a branch first, and make any necessary changes
for the release.

```
git checkout -b v0.0.2
vi pygameweb/__init__.py __version__ = '0.0.2'
git commit -m "Version 0.0.2"
```

Change log, drafting a release.
-------------------------------

Github 'releases' are done as well.
You can start drafting the release notes in there before the tag.
https://help.github.com/articles/creating-releases/

You can make the release notes with the help of the changes since last release.
https://github.com/pygame/pygameweb/compare/0.0.1...master

git log 0.0.1...master

Tagging a release
-----------------

When the release is tagged, pushing it starts the deploy to pypi off.
```
git tag -a 0.0.2
git push origin 0.0.2
```
Note: do not tag pre releases
(these are made on commits to `master`/`mastertest`).

After the tag is pushed, then you can do the release
in github from your draft release.


Back to dev version.
--------------------

If we were at 0.0.2 before, now we want to be at 0.0.3.dev
```
vi pygameweb/__init__.py __version__ = '0.0.3.dev'
```

Merge the release branch into master, and push that up.