You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+29-33Lines changed: 29 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,21 @@
1
-
## Cómo contribuir a este proyecto
1
+
## Contribuyendo a este proyecto
2
2
3
3
Si quieres contribuir a este proyecto, hay muchas cosas que puedes hacer.
4
4
Tenemos una etiqueta en los _issues_ del [repositorio de este
5
-
proyecto](https://github.com/pythoncanarias/pycan-web/issues) para
5
+
proyecto](https://github.com/pythoncanarias/pycan-web/issues) para
6
6
[aquellas tareas que pensamos que son un buen punto de partida](https://github.com/pythoncanarias/pycan-web/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
7
7
para empezar a contribuir
8
8
al desarrollo.
9
9
10
10
Si es la primera vez que vas a contribuir a un proyecto de _software_ libre,
11
-
quizá te sea de ayuda este documento: [Cómo hacer tu primera contribución a
12
-
Python Canarias](docs/primeros_pasos.md)
11
+
quizá te sea de ayuda este documento: [cómo hacer tu primera contribución a
12
+
Python Canarias](docs/first-contrib.md).
13
13
14
14
Además de las tareas propias de desarrollo, hay muchas otras formas de ayudar,
15
15
una de las principales es aportar nuevas ideas para mejorar la web, así
16
-
como avisarnos de cualquier error que encuentres en la misma.
16
+
como avisarnos de cualquier error que encuentres en la misma. Esto lo puedes hacer creando un nuevo _issue_[en la sección correspondiente de GitHub](https://github.com/pythoncanarias/pycan-web/issues).
17
17
18
-
Para contribuir como desarrollador, en el documento [README.md](README.md) se
19
-
explica cómo montar un entorno de desarrollo propio usando _Docker_ y
20
-
_Docker Compose_.
18
+
Para contribuir como desarrollador/a, hemos preparado un manual donde se explica [cómo montar un entorno de desarrollo](docs/dev.md) propio usando _Docker_ y _Docker Compose_.
21
19
22
20
## Sobre el idioma a usar en este proyecto
23
21
@@ -33,36 +31,34 @@ idea es ir traduciendo todos esos documentos hasta conseguir el estado mostrado
33
31
en la siguiente tabla:
34
32
35
33
| Área | Idioma |
36
-
|-----------------------|--------|
37
-
| Variables en código | 🇬🇧 |
38
-
| Comentarios en código | 🇬🇧 |
39
-
|_Commits_| 🇬🇧 |
40
-
| README | 🇪🇸 |
41
-
| Documentación | 🇪🇸 |
42
-
|_Issues_| 🇪🇸 |
43
-
| Etiquetas de _issues_| 🇪🇸 |
44
-
|_Pull Requests_| 🇪🇸 |
45
-
| Texto de la web | 🇪🇸 |
46
-
47
-
48
-
## Notas para los desarrolladores
49
-
50
-
El desarrollo consiste en una aplicación Django, y algunas partes de _frontend_
34
+
| --------------------- | ------ |
35
+
| Variables en código | 🇬🇧 |
36
+
| Comentarios en código | 🇬🇧 |
37
+
|_Commits_| 🇬🇧 |
38
+
| README | 🇪🇸 |
39
+
| Documentación | 🇪🇸 |
40
+
|_Issues_| 🇪🇸 |
41
+
| Etiquetas de _issues_| 🇪🇸 |
42
+
|_Pull Requests_| 🇪🇸 |
43
+
| Texto de la web | 🇪🇸 |
44
+
45
+
## Notas para desarrolladores
46
+
47
+
El desarrollo consiste en un proyecto Django, y algunas partes de _frontend_
51
48
escritas en _javascript_ plano. Por el momento no nos hemos decidido a usar
52
49
ningún _framework_, aunque algunos del equipo tenemos una cierta preferencia
53
50
por [vue.js](https://vuejs.org/).
54
51
55
-
Se ha intentado seguir en lo posible las prácticas habituales en Django, pero
52
+
Se ha intentado seguir en lo posible las [buenas prácticas habituales de Django](https://django-best-practices.readthedocs.io/en/latest/), pero
56
53
en algunos casos se han realizado modificaciones sobre lo que podría
57
54
considerarse un proyecto Django _estándar_. Explicaremos estas divergencias en las
58
55
siguientes secciones.
59
56
60
57
### Organización de código de las aplicaciones de Django
61
58
62
59
Como hay muchas aplicaciones o _apps_, las tenemos todas todas bajo una única
63
-
carpeta `apps`, para reducir la cantidad de _ruido_ en
64
-
la carpeta raíz. Si crees necesario añadir una nueva _app_, créala por favor al
65
-
mismo nivel que las actuales.
60
+
carpeta `apps`, para reducir la cantidad de _ruido_ en
61
+
la carpeta raíz. Si crees necesario añadir una nueva _app_, [lee este documento con atención](docs/new-app.md).
66
62
67
63
### Estilo de código
68
64
@@ -74,6 +70,8 @@ debajo de 96 caracteres por línea.
74
70
Algunos de nosotros usamos la herramienta [black](https://github.com/psf/black)
75
71
para formatear el código, pero no se considera obligatorio.
76
72
73
+
Así mismo, existen herramientas como [flake8](https://flake8.pycqa.org/en/latest/) que detectan divergencias del estilo de código frente a los estándares establecidos.
74
+
77
75
### Dependencias
78
76
79
77
Intentamos mantener el número de dependencias bajo. Un alto número de
@@ -95,8 +93,8 @@ Veamos, por ejemplo, la _app_ `notice`, que se usa para enviar notificaciones
95
93
a los miembros ante determinados eventos, como por ejemplo el aviso un mes
96
94
antes de que se venza su permanencia a la organización.
97
95
98
-
En la clase `apps.notice.models.Notice` se definen algunos métodos, pero
99
-
solo aquellos que afectan o cambian el estado del propio modelo, sin
96
+
En la clase `apps.notice.models.Notice` se definen algunos métodos, pero
97
+
solo aquellos que afectan o cambian el estado del propio modelo, sin
100
98
ninguna tercera parte implicada. En concreto, no existe un método
101
99
para enviar la notificación en si.
102
100
@@ -111,13 +109,12 @@ consultar o cambiar su estado interno, pero que cualquier interacción con
111
109
otras clases o componentes debe realizarse fuera de la clase, preferiblemente
112
110
en un módulo aparte.
113
111
114
-
115
112
### Asigna nombres únicos a las clases
116
113
117
114
Hay muchas razones para esto, pero veamos solo una. Si nos encontramos con una
118
115
nueva clase mientras examinamos el código, lo deseable es que una búsqueda o un
119
116
_grep_ por el nombre de la clase nos devuelva solo la definición y los usos de
120
-
la misma. Cualquier otra cosa que aparezca será ruido. Si tengo dos clases con
117
+
la misma. Cualquier otra cosa que aparezca será ruido. Si tengo dos clases con
121
118
el mismo nombre en ficheros diferentes, esto solo complica el entender en que
122
119
contextos y de que forma se usa cada una de las clases. Razones similares se
123
120
pueden argumentar para las variables o constantes globales.
@@ -135,10 +132,9 @@ sido preferible haber buscado otro nombre que no estuviera en conflicto con uno
135
132
ya existente (`@jileon`: Yo lo sé bien ya que fui yo el que creó la clase
136
133
duplicada).
137
134
138
-
139
135
### Funciones vs clases para vistas
140
136
141
137
Para las vistas, preferimos, en general, usar funciones en vez de vistas
142
138
basadas en clases. En ningún caso debe entenderse esta recomendación como una
143
139
prohibición de usar _CBV_, es solo que preferimos usarlas para casos sencillos
144
-
y/o triviales, y usar funciones para todo lo demás.
140
+
y/o triviales, y usar funciones para todo lo demás.
Copy file name to clipboardExpand all lines: docs/dev.md
+7-19Lines changed: 7 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
-
# Configuración para desarrollo
1
+
# Configuración del entorno de desarrollo
2
2
3
-
## Entorno de Docker
3
+
## Entorno Docker
4
4
5
5
Este proyecto tiene requisitos variados que hacen altamente recomendable configurar un entorno de desarrollo usando [Docker Compose](https://docs.docker.com/compose/).
5. Crea un superusuario que te permita acceder a la [interfaz administrativa de Django](#interfaz-administrativa):
35
35
```console
36
36
$ docker-compose exec web ./manage.py create_default_admin # admin | admin
37
37
```
@@ -42,28 +42,16 @@ Eso es todo, ahora puedes visitar http://localhost:8000/
42
42
43
43
### Interfaz Administrativa
44
44
45
-
Puedes acceder a la interfaz administrativa de Django yendo a https://docs.docker.com/compose/ y usando las credenciales `admin` / `admin`.
45
+
Puedes acceder a la interfaz administrativa de Django yendo a http://localhost:8000/admin/ usando las credenciales `admin` / `admin`.
46
46
47
47
### Multimedia
48
48
49
-
Si dispones de ficheros multimedia para testing o como copias de producción, puedes ponerlos en el directorio `$PROJECT/media`. Hay un volumen de Docker Compose configurado para cargarlos desde ahí.
50
-
51
-
## Estilo de código
52
-
53
-
Intentamos homogeneizar nuestro estilo de código en Python:
54
-
55
-
- Indentado con 4 espacios.
56
-
- Máximo ancho de línea: 79 caracteres.
57
-
- Orden de imports como indica [PEP8](https://www.python.org/dev/peps/pep-0008/#imports).
58
-
- Linter de Python: [Flake8](https://flake8.pycqa.org/en/latest/)
59
-
- Autoformateador de Python: [Black](https://github.com/psf/black)
49
+
Si dispones de ficheros multimedia para testing o como copias de producción, puedes dejarlos en el directorio `$PROJECT/media`. Hay un volumen de Docker Compose configurado para cargarlos desde ahí.
60
50
61
51
## VSCode y Docker
62
52
63
-
Si usas [Visual Studio Code](https://code.visualstudio.com/), puedes enlazar un contenedor remoto y configurar el IDE para usarlo.
64
-
65
-
Para usar el entorno de desarrollo Docker Compose en VSCode, instala la extensión [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
53
+
Si usas [Visual Studio Code](https://code.visualstudio.com/), puedes enlazar un contenedor remoto y configurar el IDE para usarlo. Para ello recomendamos instalar la extensión [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
66
54
67
55
El directorio `.devcontainer` contiene la configuración necesaria para dar soporte a esta integración. Sigue [estas instrucciones](https://code.visualstudio.com/docs/remote/containers) para habilitarlo.
68
56
69
-
> Python Malaga tiene un buen [tutorial de cómo configurar VSCode usando Docker](https://www.youtube.com/watch?v=mxpq0ntJ8T8).
57
+
> ⭐ Python Malaga tiene un buen [tutorial de cómo configurar VSCode usando Docker](https://www.youtube.com/watch?v=mxpq0ntJ8T8).
## Cómo hacer tu primera contribución a Python Canarias
1
+
## Cómo hacer tu primera contribución a Python Canarias<!-- omit in toc -->
2
2
3
-
Antes de nada, gracias por tu interés, solo eso ya significa bastante para
4
-
nosotros. Hacer una contribución al _software_ libre es muy interesante, no
5
-
solo para contribuir a la comunidad, también es una forma de aprender y
6
-
adquirir nuevas competencias, y de formar parte de nuestra comunidad.
3
+
Antes que nada, gracias por tu interés, solo estar aquí ya significa bastante para
4
+
nosotrxs. Hacer una contribución al _software_ libre es muy interesante, no
5
+
solo para contribuir a la comunidad, sino como una forma de aprender y
6
+
adquirir nuevas competencias, y a la vez de formar parte de nuestra comunidad.
7
7
8
-
### Primer paso, empezar con Git y GitHub
8
+
-[Primer paso: empezar con Git y GitHub](#primer-paso-empezar-con-git-y-github)
9
+
-[Segundo paso: hacer un _fork_ del repositorio](#segundo-paso-hacer-un-fork-del-repositorio)
10
+
-[Tercer paso: clonar el repositorio](#tercer-paso-clonar-el-repositorio)
11
+
-[Cuarto paso: crear una nueva rama](#cuarto-paso-crear-una-nueva-rama)
12
+
-[Quinto paso: incorporar tus cambios](#quinto-paso-incorporar-tus-cambios)
13
+
-[Sexto paso: exportar o entregar (_push_) los cambios locales al repositorio](#sexto-paso-exportar-o-entregar-push-los-cambios-locales-al-repositorio)
14
+
-[Séptimo paso: crear un _Pull Request_](#séptimo-paso-crear-un-pull-request)
15
+
16
+
### Primer paso: empezar con Git y GitHub
9
17
10
18
Lo primero que necesitas es un conocimiento, aunque sea básico, de Git y GitHub.
11
19
Si no sabes nada de Git ni de GitHub, te recomendamos el tutorial
@@ -17,40 +25,39 @@ puedes crearte una sin problemas, es totalmente gratuito.
17
25
18
26
Nuestro proyecto está alojado en la siguiente página:
Para crear una rama usaremos el siguiente comando:
71
78
@@ -78,8 +85,7 @@ se quedan dentro de esta rama hasta que se pueda reunificar esta rama con la
78
85
rama principal, o bien se borre esta rama y descartemos todos los cambios que
79
86
hubiera en ella.
80
87
81
-
82
-
### Sexto paso
88
+
### Quinto paso: incorporar tus cambios
83
89
84
90
Aquí es donde haces tu magia: realiza los cambios que creas oportunos,
85
91
los pruebas si puedes y los vas añadiendo a la rama. Puedes usar `git status` para
@@ -96,26 +102,26 @@ Cada vez que modifiques el código, el comando `add` tiene que ser ejecutado otr
96
102
vez para que los últimos cambios se tengan en cuenta en el área de trabajo.
97
103
98
104
Existe la forma abreviada `git add -u` para que añada al área de trabajo todos
99
-
los ficheros que hayan sido actualizados (`-u` por _updated_). Yo suelo añadir el
105
+
los ficheros que hayan sido actualizados (`-u` por _updated_). También es útil el
100
106
_flag_`-v` para que me muestre un listado de los ficheros añadidos, o sea que
101
107
quedaría así: `git add -uv`.
102
108
103
-
Cuando estés segura de tus cambios, puedes confirmarlos con la
109
+
Cuando estés segura de tus cambios, puedes confirmarlos con la
104
110
orden `commit` de Git:
105
111
106
112
```shell
107
113
git commit -m "Comentario describiendo los cambios realizados"
108
114
```
109
115
110
-
Nota: No es necesario que hagas un único _commit_ al final, puedes realizar todos
111
-
los commits que quieras, pero si es verdad que el paso previo a subir el código
112
-
al repositorio debe ser un `commit`. Si no lo hacemos así, quedarían cambios
113
-
el el área de trabajo no confirmadas y, por tanto, ignoradas en el siguiente
114
-
paso, en el `push`.
115
-
116
-
### Séptimo paso, exportar o entregar (_push_) los cambios locales al repositorio.
116
+
> Nota: No es necesario que hagas un único _commit_ al final, puedes realizar todos
117
+
> los commits que quieras, pero si es verdad que el paso previo a subir el código
118
+
> al repositorio debe ser un `commit`. Si no lo hacemos así, quedarían cambios
119
+
> el el área de trabajo no confirmadas y, por tanto, ignoradas en el siguiente
120
+
> paso, en el `push`.
117
121
118
-
Como se comentó antes, el comando básico aquí es `push`:
122
+
### Sexto paso: exportar o entregar (_push_) los cambios locales al repositorio
123
+
124
+
Como se comentó antes, el comando básico aquí es `push`:
119
125
120
126
```shell
121
127
git push -u origin <nombre de la rama>
@@ -124,32 +130,31 @@ git push -u origin <nombre de la rama>
124
130
Este paso crea la rama en el repositorio remoto y sube todos los
125
131
cambios que estén confirmados en el área de trabajo.
126
132
127
-
### Octavo paso, crear un _Pull Request_
133
+
### Séptimo paso: crear un _Pull Request_
128
134
129
135
Una vez que tus cambios están en tu repositorio, están listos para
130
136
realizar un _Pull Request_, que básicamente es una solicitud hecha para
131
-
incorporar los cambios incluidos en una rama a otra rama.
137
+
incorporar los cambios incluidos desde una rama a otra rama.
132
138
133
139
En este caso, lo que debemos hacer es un _Pull Request_ indicando que queremos
134
-
incorporar los cambios realizados en nuestra rama hacia la rama `mastar` del
140
+
incorporar los cambios realizados en nuestra rama hacia la rama `main` del
135
141
repositorio original (Es decir, el repositorio de Python Canarias desde
136
142
el cual se hizo el _fork_ en el paso dos).
137
143
138
144
Para ello, abrimos el navegador apuntando a nuestro repositorio en GitHub y
139
145
pulsamos el botón que reza "_Compare and Pull Request_". Si todo ha ido bien
140
146
nosotros, los mantenedores del repositorio original, seremos notificados
141
-
de los cambios y podremos revisarlos y si los encontramos adecuados,
142
-
incorporarlos al mismo.
143
-
144
-
Felicidades, acabas de realizar tu aportación a Python Canarias.
147
+
de los cambios y podremos revisarlos. Si los encontramos adecuados,
148
+
los incorporaremos en la rama de producción. En caso contrario se hará una revisión solicitando una serie de cambios que puedes aportar en la misma rama que has utilizado.
145
149
150
+
**¡Felicidades, acabas de realizar tu primera aportación a Python Canarias!** 🎉
146
151
147
-
### Enlaces interesantes
152
+
### Enlaces de interés <!-- omit in toc -->
148
153
149
-
-[La guía para principiantes de Git y Github](https://www.freecodecamp.org/espanol/news/guia-para-principiantes-untitled/) de FreeCodeCamp
154
+
-[La guía para principiantes de Git y Github](https://www.freecodecamp.org/espanol/news/guia-para-principiantes-untitled/) de FreeCodeCamp.
150
155
151
-
-[Hacktoberfest](https://hacktoberfestes.dev/)
156
+
-[Hacktoberfest](https://hacktoberfestes.dev/).
152
157
153
-
-[Make your first open source contribution](https://markodenic.com/make-your-first-open-source-contribution/) de Marko Denic
158
+
-[Make your first open source contribution](https://markodenic.com/make-your-first-open-source-contribution/) de Marko Denic.
154
159
155
-
-[Recursos de Programación](https://github.com/Acadeller/recursos-programacion)
160
+
-[Recursos de Programación](https://github.com/Acadeller/recursos-programacion).
0 commit comments