diff --git a/LICENSE b/LICENSE index dd11a10b..f5a03579 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License -Copyright (c) 2012, 2013 American Go Association +Copyright (c) American Go Association Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 31b34e65..e5864388 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,58 @@ -## AGAGD - the American Go Association Games Database -The AGAGD is a django web application ported from the EuroGo Games Database to Python that provides: +# The American Go Association Games Database (AGAGD) -* member information, -* top tournaments listings, -* top players listings, -* top active players, -* insights into current and past tournaments. +The `AGAGD` application is what runs [agagd.usgo.org](https://agagd.usgo.org). Originally, ported from the EuroGo Games Database, the `AGAGD` application now provides a means for members and non-members tournament information, chapter informaiton and member insights. + +## Contents + +* [Contributing](#contributing) +* [Requirements](#requirements) +* [Getting Started](#getting_started) +* [Triage](#triage) +* [Caveats](#caveats) +* [License](#license) ## Contributing -We welcome and encourage contributions to the AGAGD with Pull Requests (PRs), feature requests, bug reports, etc. +We welcome any contributions. You could update documentation or our getting started or add a feature or find another way to improve the `AGAGD` application. Any contributions should be submitted as Pull Requests (PR). If you new to contributing on Github, take a look a the [First Contributions](https://firstcontributions.github.io/) project. + +## Requirements + +The `ÀGAGD` application uses Docker Compose and containers for local development. As such, we require that you have Docker and Docker compose installed on your system. To run our `AGAGD` application you currently need a `schema.sql` from the repository [usgo-sql-schemas](https://github.com/usgo/usgo-sql-schemas/blob/main/schema.sql). + +## Getting Started + +### Pre-Requisites + +* [Git](https://git-scm.com/) +* [Docker](https://docs.docker.com/get-docker/) +* [Docker Compose](https://docs.docker.com/compose/install/) +* [schema.sql](https://github.com/usgo/usgo-sql-schemas/blob/main/schema.sql) + +### Get a local copy of `schema.sql` + +`$ curl -sSL https://raw.githubusercontent.com/usgo/usgo-sql-schemas/main/schema.sql -o schema.sql` + +### Run the `AGAGD` application using + +`$ docker-compose up` + +### Run tests for the `AGAGD` application using + +`$ docker-compose -f docker-compose.test.yml run test_app` -## Database Prerequisites +### The `AGAGD` app should now be running at -Contributors submitting Pull Requests (PRs) will require a `schema.sql` file within their local AGAGD repository. The `schema.sql` can be found in [USGO SQL Schema's Repo](https://github.com/usgo/usgo-sql-schemas). +[http://localhost:8000](http://localhost:8000) -## Project Priorities +## Triage [Bug Triage](https://github.com/usgo/agagd/projects/1) project for the AGAGD which lists and organizes current priorites the AGA Development Team has for the AGAGD. -## Additional Documentation +## Caveats -* [/docs](/docs) +* By default, the fake_data fixture data will be re-installed on every run of the app. This may erase any local changes you made previously. To disable this functionality, you can create a `docker-compose.override.yml` file and set `LOAD_FIXTURES` to `"false"`. See the [docker-compose documentation](https://docs.docker.com/compose/extends/#understanding-multiple-compose-files) for more information on overriding docker-compose values. ## License -The AGAGD is licensed under the MIT License which can be found in [LICENSE](/LICENSEE). +MIT © [American Go Association](/LICENSE) diff --git a/docs/docker.md b/docs/docker.md deleted file mode 100644 index c47bfacb..00000000 --- a/docs/docker.md +++ /dev/null @@ -1,42 +0,0 @@ -# Running agagd locally via docker - -## Overview - -Docker can automate much of the configuration for you. - -## Using docker - -### Prerequisites - -* Recent versions of `docker` and `docker-compose`. -* A database dump of the full AGAGD schema, stored at `schema.sql`. (in the root directory of the repository) - -### Running a dev environment using Docker - -If you wish to change the environmental variables, the `.env` file to provides values for the environmental variables. Additional information about how docker-compose uses env-files can be found on [Environmental File](https://docs.docker.com/compose/env-file/). - -These values will be used by both the database and the app. Now, run either: - -#### For Python 2.7 - -~~~shell -$ docker-compose up --build -~~~ - -#### For Python 3.7 - -##### Note: Python 3.7+ is not fully supported by the AGAGD Application. More information can be found in issue #112. - -~~~shell -$ docker-compose -f docker-compose-python3.yml up --build -~~~ - -Wait for the database to initialize and the app to start up. (there will be something like `spawned uWSGI worker` in the logs) - -You should now be serving the app at http://localhost:8000. - -### Caveats - -* New changes will only be picked up when you re-build the container, e.g. with `docker-compose up --force-recreate --build`. -* The database/tables will persist between builds and runs. If you need to clear out the database and start over from scratch, run `docker-compose down` and then `docker volume rm agagd_database`. -* By default, the fake_data fixture data will be re-installed on every run of the app. This may erase any local changes you made previously. To disable this functionality, you can create a `docker-compose.override.yml` file and set `LOAD_FIXTURES` to `"false"`. See the [docker-compose documentation](https://docs.docker.com/compose/extends/#understanding-multiple-compose-files) for more information on overriding docker-compose values. diff --git a/docs/readme.md b/docs/readme.md deleted file mode 100644 index f0a092b4..00000000 --- a/docs/readme.md +++ /dev/null @@ -1,23 +0,0 @@ -# AGAGD - -## Overview - -An app to display users, games, tournaments, and ratings information on the AGA website. -The AGAGD is a port of the old EuroGO Games Database to python developed for the [American Go Association (AGA)](usgo.org). - -## Development - -### Code Style - -The AGAGD project uses pre-commit for some basic linting and mostly follows [black](https://github.com/psf/black), so before it is required to have pre-commit installed and any errors fixed before making a pull request. ([Pre Commit](https://pre-commit.com/), [DJango Code Style](https://docs.djangoproject.com/en/3.2/internals/contributing/writing-code/coding-style/)) - -#### Install pre-commit - -* `$ pip3 install pre-commit` -* `$ pre-commit install` - -### Getting started - -**Important: running the agagd locally now requires the `schema.sql` which can be found in [USGO SQL Schema's Repo](https://github.com/usgo/usgo-sql-schemas). The `schema.sql` file needs to be place in the main directory of the locally cloned AGAGD repo.** - -The AGAGD application uses docker for local development. Information about how to get up and running see [docker.md](docker.md) for details.