diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9fa2a14..68aa5721 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,150 +1,82 @@ # Contribuyendo con la web de PyAr -## Calidad mínima del código +Podes contribuir de muchas maneras: -1. El código debe ser pep8 válido. -2. Los nombres de variables y comentarios docstring son en inglés. -3. Los docstrings tienen que ser de la forma """This is a docstring.""" osea, + Escribiendo código + Mejorando la documentación. + Reportando errores. + + +## Código de conducta + +Al contribuir en este proyecto estás formando parte de la comunidad de Python Argentina. Como miembro te pedimos que +nos ayudes a mantener nuestra comunidad abierta e inclusiva. También te pedimos que leas y respetes nuestro +[*Código de Conducta*](https://ac.python.org.ar/#coc) + + +## Reportando errores + +Una de las maneras más simples de ayudar es reportar errores. :-) + +Los errores se reportan en: https://github.com/PyAr/pyarweb/issues/ + +* Describí siempre qué esperabas que pasé y qué sucedió en su lugar. +* De ser posible incluí un ejemplo mínimo de cómo reproducir el error. +* Incluí tracebacks, screenshots, logs de errores. +* Detallá la versiónes de tu browser, sistema operativo, etc. +* En caso que estes desarrollando con la web la versión de python que estabas utilizando. + +## Escribiendo código + +Configurá tu entorno +-------------------- + +- Asegurate de tener instalada la [última versión de git](https://git-scm.com/downloads). +- Configurá git con tu [usuario](https://help.github.com/articles/setting-your-username-in-git/) y [email](https://help.github.com/articles/setting-your-email-in-git/):: + + git config --global user.name 'tu nombre' + git config --global user.email 'tu email' + +- Asegurate de tener una cuenta de [GitHub](https://github.com/join). +- "Forkea" *pyarweb* a tu cuenta de GitHub haciendo click en el botón de [Fork](https://github.com/PyAr/pyarweb/fork). +- [Clona](https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork) tu fork en tu computadora:: + + git clone https://github.com/{username}/pyarweb + cd pyarweb + +- Agregá el repositorio principal como **remote** para posteriores actualizaciones:: + + git remote add pyar https://github.com/PyAr/pyarweb + git fetch pyar + + +- Ejecta pyarweb + +Podés ejecutar pyarweb utilizando Docker o en tu maquina local. + +[Docker](https://github.com/PyAr/pyarweb/wiki/Instalacion-con-Docker) +[Virtualenv](https://github.com/PyAr/pyarweb/wiki/Instalaci%C3%B3n-manual) + + +Empeza a escribir código +------------------------ + +- Generá un nuevo branch que identifique el issue en el que vas a trabajar. (EJ: ``issue_24_nueva_funcionalidad``) +- Escribí el código utilizando tu editor preferido. + +- El código debe ser [PEP8](https://pep8.org/) válido. Aunque podes ignorar el ancho de lineas. Estamos usando 99 columnas. +- Los nombres de variables y comentarios docstring son en inglés. +- Los docstrings tienen que ser de la forma """This is a docstring.""" osea, comenzar con mayúscula y terminar con un '.' al final. Casos como: """ this is a docstring.""" o """this is a docstring.""" o """This is a docstring""" no son válidos. -4. La identación debe ser a 4 espacios, no usar tabulador o algún tipo de +- La identación debe ser a 4 espacios, no usar tabulador o algún tipo de identación diferente a 4 espacios. -5. Las urls deben estar escritas en español por un tema de SEO issues #163 -6. Todo cambio en los modelos debe ir acompañado de su respectiva migración. -7. Agregar tests de los cambios suman!, sobretodo ahora que no hay suficientes - ;). - -## Como trabajar con Github y los pull requests? - -1. Tener una cuenta en github, y estar logueado en github. - -2. Ingresar a https://github.com/PyAr/pyarweb, y forkear el proyecto. -Al forkear el proyecto, github hace una copia entera del proyecto y lo -crea como un repositorio donde vos sos el propietario, osea un repositorio -tuyo. Es como un "copy/paste" desde la "compu de pyar" a tu "compu". Esto -quiere decir que las modificaciones que hagas en el fuente estarán en tu -repositorio, pero no en el repositorio de PyAr. Para poder enviar las -modificaciones presentes en tu repositorio (en tu fork), es que luego vas -a crear un Pull Request. Podes forkear el proyecto de PyAr haciendo click -en el botón "Fork" que lo podes encontrar en la parte superior a la derecha. - -3. Una vez forkeado el proyecto, te lo clonas. Siempre recordar trabajar -sobre el branch "develop". A continuación un ejemplo: - ``` - [edvm@laptop mixes] $ git clone git@github.com:edvm/pyarweb.git pyar - Cloning into 'pyar'... - remote: Counting objects: 3007, done. - remote: Total 3007 (delta 0), reused 0 (delta 0), pack-reused 3006 - Receiving objects: 100% (3007/3007), 822.01 KiB | 73.00 KiB/s, done. - Resolving deltas: 100% (1917/1917), done. - Checking connectivity... done. - [edvm@laptop mixes] $ cd pyar - [edvm@laptop pyar] (master) $ git checkout develop - Branch develop set up to track remote branch develop from origin. - Switched to a new branch 'develop' - [edvm@laptop pyar] (develop) $ git branch -r - origin/HEAD -> origin/master - origin/develop - origin/master - origin/waliki - [edvm@laptop pyar] (develop) $ git pull origin develop - From github.com:edvm/pyarweb - * branch develop -> FETCH_HEAD - Already up-to-date. - [edvm@laptop pyar] (develop) - ``` - -4. Hacer tus modificaciones en el branch "develop" no es la mejor práctica. -Un pull-request en github representa una peticion de merge (de pull = fetch + merge), -y como tal, todos los commits que estén en la rama "que se pide mezclar" -irán a parar a la rama destino. Esto significa, siguiendo las buenas practicas -de git-flow que se menciona más abajo, que lo mejor es hacer un branch local, -hacer todos los commits allí, pushear ese branch al repo propio y crear el PR -contra el develop de pyar. Los PR develop -> develop complican trabajar en dos -o más pull request en paralelo y sincronizar con el branch upstream (el "develop" oficial) -Te tiro un tip por si no lo conocías, usar "git flow" es genial! -http://nvie.com/posts/a-successful-git-branching-model/ - -5. Perfecto, entonces instalate "git flow", te lees el link de arriba para -entender que hace/significa git flow, una vez hecho eso comenzas a trabajar -por ejemplo en el issue-20: - - [edvm@laptop pyar] (develop) $ git flow feature start issue-20 - Switched to a new branch 'feature/issue-20' - Summary of actions: - - A new branch 'feature/issue-20' was created, based on 'develop' - - You are now on branch 'feature/issue-20' - Now, start committing on your feature. When done, use: - git flow feature finish issue-20 - [edvm@laptop pyar] (feature/issue-20) - -Es importante leer lo que te dice la consola, quiero resaltar las siguientes -dos lineas: - - - A new branch 'feature/issue-20' was created, based on 'develop' - - You are now on branch 'feature/issue-20' - -Esto quiere decir que un nuevo branch llamado 'feature/issue-20' fue creado -a partir de 'develop', y que ahora vos estas parado sobre el branch -'feature/issue-20'. - -Ahora meto codigo, modifico, comiteo, comiteo, comiteo muy seguido, una -vez termino con mi tarea es hora de integrar los cambios que acabo de -hacer al branch "develop" de mi compu, el local, por ejemplo: - - [edvm@laptop pyar] (feature/issue-20) $ git flow feature finish issue-20 - Switched to branch 'develop' - Your branch is up-to-date with 'origin/develop'. - Already up-to-date. - Deleted branch feature/issue-20 (was ba56278). - Summary of actions: - - The feature branch 'feature/issue-20' was merged into 'develop' - - Feature branch 'feature/issue-20' has been removed - - You are now on branch 'develop' - [edvm@laptop pyar] (develop) $ - -Repasando el "summary of actions", lo que acaba de hacer: - - - The feature branch 'feature/issue-20' was merged into 'develop' - - Feature branch 'feature/issue-20' has been removed - - You are now on branch 'develop' - -Primero hizo merge de los cambios existentes en el branch 'feature/issue-20' -al branch 'develop', luego borra el branch local 'feature/issue-20' (que es -el branch local), y te deja parado en el branch 'develop'. - -Finalmente subis tus cambios a Github: - - [edvm@laptop pyar] (develop) $ git push origin develop - .... - - -6. Genial, ahora tus cambios están subidos a tu branch "develop" en Github. -Queres integrar esos cambios con el branch "develop" de PyAr, y la forma -en que se hace es creando a lo que le llaman "Pull Request", que le -pusieron ese nombre, pero para mi tiene más sentido si se llamara -"Push Request", porque lo que queres hacer es mandar/"pushear" código jeje. -Bueno, para crear el Pull Request vas a la url de tu fork, en mi caso es: -https://github.com/edvm/pyarweb/tree/develop - -Asegurate de seleccionar como branch "develop", vas a ver un botón verde -que dice "Compare and Pull Request". Le das click, te va a pedir algunos -datos. El title sería como el "subject", un mensaje corto bien descriptivo -por ejemplo: "Resuelvo el issue #13", y en el body/cuerpo del mensaje, si -lo consideras necesario podes escribir lo que quieras. Finalmente le das -click al botón verde "Create pull request", eso es todo! Lo que acaba de -suceder, es que el repositorio "PyAr" recibe una notificación de que hay -un "Pull Request" pendiente de revisión. En ese momento se revisa el -PR (pull request) y si todo esta ok, PyAr acepta el PR y tus cambios -quedan integrados en el repositorio de PyAr. Puede también suceder que -no se acepte el PR y te comenten el porque no se aceptó, quizá hay algún -error en el código, etc. Animos! es cuestión de corregir lo comentado, -y volver a comenzar desde el punto 4 :). - -7. Más referencias sobre los pull requests: - -- https://help.github.com/articles/creating-a-pull-request/ - +- Las urls deben estar escritas en español por un tema de SEO issues #163 +- Todo cambio en los modelos debe ir acompañado de su respectiva migración. +- Agregar tests de los cambios suman!, sobretodo ahora que no hay suficientes ;). +- Hace push de tus commits a GitHub y [generá un a pull request](https://help.github.com/articles/creating-a-pull-request/). +- Festeja!! 🎉 + Para más información consultá en el [*Manual básico de supervivencia para colaborar con el sitio de PyAr*](https://github.com/PyAr/pyarweb/wiki/Manual-b%C3%A1sico-de-supervivencia-para-colaborar-con-el-sitio-de-PyAr). diff --git a/INSTALLATION.md b/INSTALLATION.md index db1095f2..7a8771de 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,67 +1,3 @@ -# Installation Notes +## Guia de instalación -## Prerequisites - -Make sure you have installed... - -```bash -sudo apt-get install python3-dev libxml2-dev libxslt1-dev zlib1g-dev libffi-dev openssl-dev -``` - -## Create virtualenv - -You should use virtualenv (or [FADES](https://github.com/PyAr/fades)). Currently supports 3.5. -Create a virtualenv named `pyarweb` - -### Pyenv - -```bash -pyvenv3 pyarweb -``` - -### Virtualenvwrapper - -If you don't know how to use `virtualenvwrapper` please check [official documentation](https://virtualenvwrapper.readthedocs.io/en/latest/) - -```bash -mkvirtualenv -p $(which python3) pyarweb -``` - -## Install requirements - -```bash -pip install -r dev_requirements.txt -``` - -## Create PostgresSQL DB - -### with Docker engine - -```bash -docker run --name pyarweb-db -e POSTGRES_DB=pyarweb -p 5432:5432 -d postgres -``` - -### with PostgreSQL - -```bash -su - postgres -createdb pyarweb -``` - -## Initialize DB - -```bash -./manage.py makemigrations # because Waliki presents some bug... -./manage.py migrate -``` - -## Run some test -```bash -./manage.py test -``` - -# Run service - -```bash -./manage.py runserver -``` \ No newline at end of file +Seguí los pasos en nuestra wiki: https://github.com/PyAr/pyarweb/wiki/Instalacion-con-Docker