Colaborar

Recién estamos empezando, así que hay mucho por hacer.

No sé programar o no tengo idea por dónde empezar

No todas las tareas involucran código, correcciones ortográficas también aportan al proyecto. Y si no te atreves a hacer la corrección por ti misma/o, puedes al menos reportar el problema. A continuación hemos redactado una guía para que puedas iniciar.

Si tienes dudas y/o problemas mientras sigues los pasos, no dudes en preguntar en nuestro canal de Telegram.

Ejecutar el proyecto localmente

Python

Este proyecto usa Python 3, puedes descargarlo desde https://www.python.org/downloads/. Para verificar que tienes Python 3 en tu sistema ejecuta el siguiente comando en una terminal (ventana de comandos):

Si la versión descargada de python es para Windows, es conveniente marcar la opción PATH, con la finalidad de que las variables de entorno se reconozcan en cualquier terminal abierto ya que facilita la ejecución a futuro del comando pip install y no lo restringe al directorio de instalación.

$ python --version
Python 3.6.5

Si el comando anterior no funcionó en Windows puedes intentar:

> py --version
Python 3.6.5

Si la salida del comando es diferente, no te preocupes, sólo debes asegurarte que el primer número sea un 3. En caso que la salida haya sido algo como 2.7.14, intenta con el comando python3 --version.

En caso que ambos comandos te den un error o no sea la versión adecuada, asegúrate que Python esté en tu PATH o instala la versión adecuada.

Obteniendo el proyecto

El proyecto está bajo el sistema de control de versiones Git y alojado en GitHub, puedes descargar Git desde https://git-scm.com/download , o seguir nuestra guía de instalación de Git. Para verificar que tienes Git en tu sistema ejecuta el siguiente comando en una terminal (ventana de comandos):

$ git --version
git version 2.17.1

Luego de instalar Git se debe configurar el usuario y el correo electrónico con los siguientes comandos:

git config --global user.name "Juanito Perez"
git config --global user.email "[email protected]"

Debes tener una cuenta en GitHub, inicia sesión, dirígete al proyecto de Python Ecuador y puedes darle una estrellita al repositorio.

/images/guias/colaborar/estrellita.png

Y luego presionar el botón Fork para hacer un fork del proyecto en tu cuenta.

/images/guias/colaborar/fork.png

Puedes dejar los ajustes por defecto y presionar el botón Create fork

/images/guias/colaborar/newfork.png

Para obtener el código puedes:

Copiar el enlace del repositorio en el botón Clone y luego en el ícono de copiar

/images/guias/colaborar/clone.png

En una terminal ejecuta el comando:

git clone {pegar-enlace-con-ctrl+shift+v}

O directamente ejecuta el siguiente comando en una terminal. Donde {tu-usuario} es tu usuario de GitHub.

git clone https://github.com/{tu-usuario}/pythonecuador.github.io.git

Por ejemplo, para el usuario Marlon5300:

git clone https://github.com/Marlon5300/pythonecuador.github.io.git

Entra al directorio que contiene el código fuente con

cd PythonEcuador.github.io

Ejecutando el proyecto

El sitio está construido usando Nikola (no es necesario que sepas usarlo para empezar a colaborar en el proyecto).

Crea un entorno virtual para instalar las dependencias de Python (este paso debes hacerlo sólo una vez):

python -m venv venv

Con ese comando acabamos de crear un entorno virtual llamado venv. Puedes leer más sobre los entornos virtuales de Python en https://docs.python.org/3/library/venv.html.

Ahora necesitamos activar el entorno virtual (este paso debes hacerlo cada vez que abras una nuevo terminal):

# Para sistemas Linux y Mac
source venv/bin/activate

# Para sistemas Windows
venv\Scripts\activate

# Para sistemas Windows, usando Git bash
venv/Scripts/activate

# Si el comando anterior no funciona puedes probar:
source venv/Scripts/activate

Ahora ya podemos instalar Nikola y otras dependencias:

pip install -U pip setuptools wheel
pip install -r requirements.txt

Finalmente, para ejecutar el sitio con Nikola

nikola build
nikola serve

Si abres tu navegador e ingresas a http://127.0.0.1:8000/ podrás ver el sitio.

/images/guias/colaborar/site.png

Ejecutando los tests

Para ejecutar las pruebas instalamos nox en el entorno virtual creado, con el siguiente comando.

pip install nox

Usamos el comando nox para ejecutar las pruebas configuradas en el archivo noxfile.py del proyecto.

nox

Deberías obtener un resultado como este, indicando los posibles errores o tests fallidos:

/images/guias/colaborar/tests.png

Reportando errores (bugs)

GitHub usa issues para dar seguimiento a tareas y reportar bugs. Si encuentras un error o tienes una idea para mejorar el sitio, crea un nuevo issue describiendo el bug/mejora.

Buscando tareas

Puedes mirar en los issues abiertos para buscar tareas por hacer. Los issues contienen etiquetas (labels) para clasificarlos por complejidad y/o tipo.

/images/guias/colaborar/search_issue.png

good first issue

Tareas de complejidad fácil que te ayudarán a familiarizarte con el proyecto.

bug, enhancement

Si ya resolviste suficientes tareas fáciles y quieres pasar al siguiente nivel.

decision needed

Indica que hace falta tomar una decisión para resolver el problema.

design

Si lo tuyo es el diseño gráfico o web.

help wanted

Indica que uno de los administradores busca ayuda en un issue o pull request

ready

Indica que el issue esta listo

wip

Indica que el issue está en progreso (Work in Progress)

wontfix

Indica que el trabajo no va a continuar en un issue o pull request

sponsor

Indica que se debe agregar un nuevo sponsor mediante pull request

También puedes ayudar revisando pull requests.

Realizando cambios

Una vez que tengas un issue con cual trabajar. Crea una nueva rama con un nombre relacionado al issue que estás resolviendo. arregla-issue-13 es el nombre de la rama usada en este ejemplo.

git checkout -b arregla-issue-13

Haz los cambios que sean pertinentes para resolver el issue. Puedes ver los cambios en tu navegador mientras editas los archivos con el siguiente comando

nikola auto

Para visualizar los archivos modificados y el estado del area de trabajo usa el siguiente comando.

git status

Trata de hacer un commit por cada bloque de cambios relacionados que hagas

git add archivo-editado.rst
git commit -m "Arreglada falta ortográfica"

Una vez que hayas hechos todos los cambios necesarios, súbelos a tu fork

git push -u origin arregla-issue-13

Dirígete a la página del proyecto y verás un mensaje sugiriéndote hacer un pull request (PR).

/images/guias/colaborar/notice.png

En la descripción del PR describe brevemente los cambios que hiciste, no olvidar poner Close #n, donde n es el número del issue que estás resolviendo. Luego haces clic en Create pull request.

/images/guias/colaborar/PR.png

Espera a que un miembro de la comunidad revise tu PR, si son necesarios más cambios, los puedes hacer en la misma rama y repetir el proceso de agregar más commits.

git add archivo-editado.rst
git commit -m "Más cambios"

Una vez que ya los tengas listos, vuelve a subirlos. Se agregarán al PR creado.

git push

Si no son necesarios más cambios y tu PR es aprobada, sólo debes esperar a que un miembro de la comunidad haga un merge.

Estructura del proyecto

files/

Archivos generales del sitio

pages/

Aquí están todas las páginas del sitio

posts/

Posts del sitio

themes/custom/

Tema personalizado del sitio

themes/custom/assets/

JavaScript, CSS, etc

themes/custom/templates/

Aquí están los templates; son archivos parecidos a html reutilizables

conf.py

En este archivo están las configuraciones del sitio

Editar una página incompleta

Si te topaste con una página con el título ¡Esta sección necesita de tu ayuda!, para empezar a editarla debes localizar la página (se encuentran en el directorio pages/) cada archivo corresponde a la URL de la página, por ejemplo si la página es www.python.ec/eventos el archivo a editar se encontrará en pages/eventos.rst. Los archivos están escritos en reStructuredText. Tenemos un minitutorial de reStructuredText que puedes seguir aquí.

¡Pero ahí no está toda la página que vi en el navegador!

Ya vamos a esa parte.

Como podrás notar, al principio del archivo, se encuentran metadatos. Como:

  • title: El título de la página

  • slug: El path del URL

  • template: El template a ser usado para la página

Existen otros, pero esos son los más relevantes, sobre todo el de template. Por defecto estará en ayuda.tmpl, tu primer paso será cambiarlo por pagina.tmpl. Estos templates contienen el contenido base de la página (se encuentran en themes/custom/templates/). Y los archivos .rst sólo contienen el texto principal.

Ahora sólo necesitas editar el archivo .rst ¡y listo!

Crear una nueva página

Crea un archvivo .rst dentro del directorio pages/ utiliza guiones medios para separar las palabras, guíate de las otras páginas para escribir los metadatos al principio del archivo o puedes simplemente copiar y pegar una página ya existente, edítala ¡y listo!

Creando una nueva sección

Pronto

Mi segundo Pull Request

¿Ya por el segundo? ¡Felicitaciones! Antes de enviar tu segundo pull request, debes hacer un par de pasos para igualar tu fork con los últimos cambios del repositorio.

Primero debemos cambiarnos nuevamente a la rama principal (main).

git checkout main

Asegúrate que no tengas cambios residuales de tu anterior PR antes de proceder con los siguientes pasos (puedes usar git status para comprobarlo).

Necesitaremos hacerle saber a git del repo principal con el siguiente comando.

git remote add upstream https://github.com/PythonEcuador/PythonEcuador.github.io.git

Podemos comprobar que se añadio el repo principal con:

git remote -v

/images/guias/colaborar/listar_remotos.png

Ahora ya podemos bajarnos los últimos cambios del repo principal.

git pull upstream main

/images/guias/colaborar/pull_upstream.png

Y los subimos a nuestro fork

git push origin main

/images/guias/colaborar/push_origin_src.png

Ahora si, puedes seguir los pasos indicados arriba para continuar con tu próximo pull request.

FAQ

¿Qué es un sitio estático?

Es un sitio con contenido que nunca cambia, a diferencia de un sitio dinámico dónde el contenido cambia con interacciones de los usuarios.

¿Por qué no se hizo un sitio dinámico usando un framework como Django?

Un sitio estático no requiere de un servidor ni de mucho esfuerzo para desplegar. Puede ser alojado en GitHub Pages sin ningún costo. Es totalmente escalable y configurable.

¿Por qué se usó Nikola?

Se hizo una pequeña votación antes de empezar con el desarrollo del sitio en #2.