Browse Source

Předěláno Readme

Teď vypadá víc jako readme, na které chceš narazit v gitee, než jako pár
random tipů. Random tipy jsem přesunul do dokumentace
pull/11/head
Pavel "LEdoian" Turinsky 2 years ago
parent
commit
50eaaf9eb7
  1. 137
      README.md

137
README.md

@ -1,79 +1,58 @@
**TODO: přepsat, tohle dávno neplatí!**
Basic commands for web development
==================================
After you clone this repository, run `make`. It will download, locally install
and setup virtualenv and pip, and then locally install all required packages
from `requirements.txt`.
When working with the code, always use the binaries in `./bin/`, such as
`bin/pip`, `bin/python`, ... never the global python, pip, ...
Use `make` and `./manage.py` for most things.
Use git :-)
Quickstart
----------
Run the following commands:
make install_venv
. env/bin/activate
make install_web
Pokud install_web říká Error: pg_config executable not found. nainstaluj si libpq-dev
Pokud chybová hláška obsahuje #include <Python.h>, nainstaluj si python3-dev
After finishing development, run "deactivate".
Make commands
-------------
* `make install` (or `make`) - locally install and setup virtualpy, install
required packages. Ran again installs missing packages. Run after changing
`requirements.txt`.
* `make clean` - remove local python packages.
* `make veryclean` - remove local packages and virtualpy enviroment and
binaries.
* `make run` - runs "./manage.py runserver_plus"
* `make push_test` - pushes the last commited version to test location.
Only git-commited changes are pushed! Rest is re-generated from scratch.
At test server, the media data and database are kept the same.
Everything else not in .gitignore is deleted/overwritten on the test server.
* `make schema` - generates graph of seminar and all schemas as PDF. Supercool!
* `make sync_prod_flatpages` - downloads and applies static/flat pages from mamweb-prod
./manage.py commands
--------------------
* `./manage.py migrate` - update the database schema, initialise the database.
You need to run this in the beginning.
* `./manage.py runserver_plus` - run a debugging server for the web. Slightly
enhanced compared to `./manage.py runserver`.
Open [127.0.0.1:8000](127.0.0.1:8000).
* `./manage.py testdata` - create pseudo-random seminar data and admin/admin
user.
* `./manage.py test` - run the tests.
* `./manage.py shell` - run commands, list elemements of database, check syntax
by importing files, etc.
Configurations
--------------
* `mamweb/settings_common.py` contains most configuration options.
* `mamweb/settings.py` is used only for local development.
* `mamweb/settings_test.py` is used for testing on atrey.
* `mamweb/settings_prod.py` is used in production deployment.
These are automatically switched by `make`.
Web M&M
======
Tohle je repozitář s kódem M&Mího webu. Pokud zde hledáte web samotný nebo
informace o semináři, najdete je na <https://mam.matfyz.cz> (a upřímně nechápu,
jak jste se dostali k tomuhle textu :-D)
Pokud jste tu zůstali, tak vás beztak zajímá vývoj webu (a jestli ne, tak
budeme rádi, když začne :-)).
Co je M&Mweb uvnitř
------
Celý náš web je napsaný v [Pythonu](https://www.python.org) ve frameworku
[Django](https://www.djangoproject.com/). Web běží na serveru zvaném Gimli,
jako databázi používá PostgreSQL (pro lokální vývoj naopak SQLite) a všechen
náš kód je uložený v [Gitu](https://git-scm.com/) na [téhle
gitee](https://gitea.ks.matfyz.cz/). Pro dokumentaci používáme
[Sphinx](https://www.sphinx-doc.org).
<!--TODO: Z odstavce výše by ideálně měla být zachována jen první věta a zbytek
by měl být někde v docs s podrobnějším popisem…-->
Jak si web pořídit
------
Prosím přečti si podrobnější návod v <docs/vyvoj.rst> (tady by bylo zbytečné
ho duplikovat).
Jak web vyvíjet
----
<!--TODO: Napsat obšírněji, asi zase do docs/-->
Na webu je mnoho věcí k dělání, některé ani nevyžadují kódění (třeba uhánění
orgů, aby si psali medailonky, aktualizace fotek, …), některé se naopak týkají
infrastruktury pod kódem (Gitea, Gimli, …). Je proto těžké mít na to úplně
obecný návod, tak tady je zhruba návod na úpravy kódu a pokud se něco z toho
nedá aplikovat, tak to prostě zkus nějak udělat jinak, po svém. (Omlouvám se
neinformatikům, ale líp to teď nesepíšu :-))
1. Nejprve si stáhni repozitář a rozběhni si lokální web u sebe (viz <docs/vyvoj.rst>).
1. Najdi si problém v Kanboardu (klikni na „Issues“ na Gitee) a/nebo se domluv
s webaři, na čem bys tak mohl/a pracovat.
1. Najdi místo, kde se to dá opravit a zkus to tam opravit. Uznávám, že tenhle
bod je otravně obecný, pokud tápeš, zkus se zeptat zkušenějších webařů nebo
podívat do dokumentace.
1. Vyzkoušej, že ti to lokálně funguje tak, jak má.
1. Zvládneš-li a máš-li čas, zkus to i zdokumentovat a/nebo napsat testy (TODO: chybí návod)
1. Po dohodě s webaři to vyzkoušej na testwebu
1. Pošli pull-request a případně zkus reagovat na komentáře
1. Až se změna začlení do hlavní větve (`master`) a nasadí se web na produkci,
můžeš mít radost, že se web bude používat lépe Tobě i ostatním orgům :-)
### Proč pull-requesty?
<!--FIXME: Tohle ale už úplně patří do docs a ne sem, jen je zatím nemám prozkoumané…-->
Účelů pull-requestů je několik. Jednak doufáme, že pomůže webařům se orientovat
v kódu, jednak tím umožňujeme dělat experimenty a dávat si zpětnou vazbu. V
neposlední řadě pomáhají držet aspoň trochu konzistentní kód, což má pomoci
pohodě při programování… (A asi jsem na něco zapomněl :-))

Loading…
Cancel
Save