-
PROCEDIMIENTOS DE TRABAJO
2.1 Primeras tareas del proyecto
2.2 Configuraciones Git
2.3 Procedimiento diario
2.4 Procedimiento de trabajo con tarjetas
2.5 Aspectos a tener en cuenta al hacer una PR
2.6 Trabajo con git
2.7 Metodología Scrum -
DEFINICIONES DE MÉTODO, CLASES, ETC...
4.1 Nombre de los Packages
4.2 Nombre de las clases
4.2.1 Nombre de las clases de prueba (testing)
4.2.2 Nombre de las clases de interficie
4.3 Nombre de los métodos
4.3.1 Nombre de los métodos de prueba (testing)
4.4 Nombre de constantes
4.5 Nombres de variables locales
4.5.1 Variables temporales "throwaway"
4.6 Nombres de variables de tipo
4.7 Camel case: definido -
LIBRERÍAS USADAS
5.1 Plugins principales
5.2 Área de implementación
5.3 Área de pruebas (testing)
-
Clona el repositorio ita-challenges-backend de GitHub en tu sistema local:
git clone https://github.com/IT-Academy-BCN/ita-challenges-backend.git -
Cambie al directorio del repositorio clonado:
cd ita-challenges-backend -
Asegúrese de estar en la rama "develop". Puede verificar las ramas diponibles y su rama actual ejecutando el siguiente comando:
git branch -
Si no está en la rama "develop", cambie a ella ejecutando el siguiente comando:
git checkout develop -
Cree una nueva rama con su nombre para realizar sus cambios:
git checkout -b nombre-de-su-ramaRemplace "nombre-de-su-rama" con un nombre descriptivo que indique los cambios que planea realizar.
-
Abra el archivo contributors.md y agregue su nombre y su GitHub.
-
Después de hacer un git add y un git commit, realize el siguiente git push:
git push origin nombre-de-su-rama -
Abra el repositorio en GitHub y debería ver un mensaje que le permite crear un "pull request" desde su rama recién creada a la rama "develop". Haga clic en el enlace para crear el pull request.
-
Asegúrate de tener las MongoDB Tools instaladas. Si aún no las tienes, ve al apartado de “Programas necesarios” y sigue las instrucciones proporcionadas para descargarlas en tu sistema operativo.
-
Ahora que tienes las MongoDB Tools instaladas, abre la terminal de MongoDB ejecutando el siguiente comando:
mongosh -
Usa el siguiente comando para cambiar a la base de datos "admin":
use admin -
Una vez dentro, pega el siguiente bloque de código:
db.createUser({ user: "admin_challenge", pwd: "BYBcMJEEWw5egRUo", roles: [ { role: "dbOwner", db: "challenges" } ] }); -
Ejecuta el siguiente comando para ver si el usuario se ha creado correctamente:
show users -
Sal de la terminal de MongoDB escribiendo el siguiente comando:
exit -
Conecta a Mongo (quizás con MongoDB Compass) con el usuario que has creado en el paso 4.
-
Crea las colecciones "challenges", "languages" y "solutions" en la base de datos "challenges". Usa el siguiente comando para crear la base de datos "challenges":
use challenges -
Importa los datos de cada collection en la opción "Add Data" de Compass. O, si lo prefieres, puedes importar los datos desde la terminal con el comando (modifica las rutas para que se encuentren los ficheros de carga):
mongoimport --db=challenges --username admin_challenge --authenticationDatabase admin --password BYBcMJEEWw5egRUo --collection=challenges --jsonArray --file=./mongodb-test-data/challenges.json
mongoimport --db=challenges --username admin_challenge --authenticationDatabase admin --password BYBcMJEEWw5egRUo --collection=languages --jsonArray --file=./mongodb-test-data/languages.json
mongoimport --db=challenges --username admin_challenge --authenticationDatabase admin --password BYBcMJEEWw5egRUo --collection=solutions --jsonArray --file=./mongodb-test-data/solutions.json
- Abre MongoDB Compass, haz un "Reload Data" y ya verás la base de datos correctamente importada.
- Por favor, revisa los documentos README.md dentro de cada microservicio, puede que contengan instrucciones adicionales.
Configuraciones Git necesarias para evitar problemas
- Copie el archivo ".gitignore" del proyecto raíz
- Péguelo en el directorio del PC (fuera de la carpeta del proyecto)
- En Git Bash...
- Ejecute el comando: 'git config --global core-excludesfile ruta/.gitignore'
Where...
'Path': es la ruta de la carpeta donde se encuentra el archivo ".gitignore".
¡Nota! Esta configuración no solo te servirá para el proyecto actual, sino también para todos los proyectos que hagas con GIT.
Antes de nada, por favor revisa https://docs.github.com/es/get-started/getting-started-with-git/configuring-git-to-handle-line-endings
Ten presente que el encoding por defecto en el proyecto es UTF-8. Asegúrate de que tus editores emplean esa codificación.
- Conectarse a Teams a las 9:15h
- Hacer pull de la rama "develop"
- Hacer merge de develop con la rama en la que estás trabajando
- Si tienes alguna PR abierta, actualiza la rama con los cambios de develop
- "Coffee time" a las 10:15h aproximadamente
IMPORTANTE: Se espera que en proyecto estemos online con cámara encendida desde las 9:15h hasta las 13:15h, para trabajar en equipo (salvo circunstancias que lo justifiquen).
- En el tablero de Sprint Backlog, localiza la tarjeta que deseas asignarte. Las tarjetas están clasificadas por niveles (1, 2, 3), siendo 1 el nivel de complejidad más bajo.
- Haz clic en la tarjeta para abrirla y ver más detalles.
- En la parte de la derecha, en el campo "Assignees", si aprietas "Add assigness" se abre un desplegable con todos los participantes del proyecto y ya te puedes seleccionar a ti para asignártela.
- Una vez que te has asignado la tarjeta, tu perfil de usuario se mostrará como el responsable de la tarjeta.
- Te puedes asignar cualquier tarjeta que esté en la columna "Todo" siempre y cuando esté libre.
- Cuando empieces a trabajar con la tarjeta, la deberás mover a la columna "Doing".
- Cuando la tarea de la tarjeta haya sido completada y hayas hecho la PR a la rama "develop", puedes mover la tarjeta a la columna "Testing" para indicar que ya está lista para ser probada.
- Finalmente, cuando tu PR haya sido aceptada y, por lo tanto, la tarjeta haya sido aprobada en las pruebas, esta se pasará a la columna "Done". Esto indica que la tarjeta se ha completado con éxito.
-
Abre tu terminal o línea de comandos y navega hasta el directorio de tu proyecto. Asegúrate de estar en la rama "develop".
-
Crea una nueva rama utilizando el formato "feature#numeroDeLaTarjeta". Se refiere al número de la tarjeta del Sprint Backlog. Por ejemplo:
git checkout -b feature#123 -
Ahora puedes comenzar a realizar los cambios en tu rama.
-
Una vez hayas realizado las modificaciones necesarias haz un push de tu rama al repositorio remoto. Si estuviésemos en la feature#123 deberíamos hacer:
git push origin feature#123 -
Finalmente, ve a GitHub donde se encuentra tu repositorio y crea un "pull request" desde tu rama "feature#123" hacia la rama "develop".
- En la página de creación de a pull request, selecciona la rama base y la rama comparada:
- La rama base es la rama a la que deseas fusionar tus cambios. En este caso es la rama "develop".
- La rama comparada es la rama que contiene tus cambios.
- Proporciona una descripción de los cambios que has realizado. Sé claro y conciso.
- Cuando hayas terminado de completar la información de la pull request, haz clic en el botón verde "Create pull request" para crearla.
- A continuación verás como se hace un análisis del build. Si el análisis pasa con éxito, se mostrará un tick verde en el resultado. Por el contrario, si detecta problemas en el código, se mostrará una aspa roja. En este caso, aprieta en "Details" y observa donde se encuentra el problema.
- SonarCloud también va a analizar tu código. Te proporcionará información sobre los bugs, vulnerabilities, security hotspots y code smell. El converage debe ser igual o superior al 80.0%.
- En caso de que debas revisar y corregir algunos problemas, actualiza tu rama local con los cambios y haz push nuevamente a la rama remota correspondiente.
- La pull request se actualizará automáticamente con los nuevos cambios realizados en tu rama.
El workflow de git que seguimos en proyecto es similar a Gitflow. Para poder trabajar en el proyecto, debería conocer al menos los siguientes comandos git:
- git clone
- git merge
- git push
- git pull
- git branch
- git checkout
Puede encontrar un buen tutorial en https://www.atlassian.com/git, y hay muchos otros recursos en https://docs.github.com/en/get-started/using-github/github-flow
En este proyecto, es importante seguir ciertas convenciones al establecer la estructura y nomenclatura de las URL's utilizadas en el backend.
A continuación, se presentan las convenciones que deben seguirse al normalizar las URL's:
-
Pluralización: se recomienda utilizar nombres plurales para los recursos en las URL's. Por ejemplo, en lugar de "/challenge", se utilizaría "/challenges".
-
Uso de sustantivos: se deben utilizar sustantivos en lugar de verbos en los nombres de los recursos para mantener una estructura coherente. Por ejemplo, "/challenges" en lugar de "/obtener-challenges".
-
Separadores: se ha establecido el uso de guiones ("-") como separador para las palabras en las URL's. Por ejemplo, "/bcn-zones"
-
Consistencia en minúsculas: las URL's deben seguir una convención de minúsculas. Por ejemplo, "/challenges" en minúsculas en lugar de "/Challenges" o "/CHALLENGES".
-
Evitar caracteres especiales: se deben evitar los caracteres especiales en las URL's y, en su lugar, utilizar caracteres alfanuméricos.
-
Orden jerárquico: si hay una jerarquía en los recursos, se debe reflejar en la estructura de las URL's. Por ejemplo, "/challenges/{challengeId}/update" para obtener los desafios del usuario.
-
Versionado: si se requiere versionar la API, se debe considerar incluir la versión en la URL. Por ejemplo, "/itachallenge/api/v1/challenge" para la versión 1 de la API de challenges.
-
Evitar verbos en URL's: en general, se recomienda evitar incluir verbos en las URL's y utilizar los métodos HTTP adecuados para realizar acciones en los recursos.
-
Consistencia con nombres de atributos: los nombres de atributos utilizados en las URL's deben ser coherentes con los nombres utilizados en el modelo de datos.
-
Evitar URL's demasiado largas: se debe evitar el uso de URL's excesivamente largas y buscar mantenerlas concisas y significativas.
Aquí se presentan algunos ejemplos de cómo deben estructurarse las URL's según las convenciones establecidas:
/challenges- Obtener una lista de todos los challenges./challenges/{challengeId}- Obtener los detalles del challenge con ID 550e8400-e29b-41d4-a716-446655440000./challenges/{challengeId}/update- Editar los detalles del challenge con ID 550e8400-e29b-41d4-a716-446655440000.
- Todo en minúscula
- Sólo letras y dígitos
- com.itachallenge.user
- exception
- helper
Oracle Code Conventions for java: 9 - Naming Conventions
Google Java Style Guide: 5.2.1 package names
- UpperCamelCase
- Sólo letras y dígitos
- UserController
- PropertiesConfig
Oracle Code Conventions for java: 9 - Naming Conventions
Google Java Style Guide: 5.2.2 class names
- UpperCamelCase
- Terminar con 'Test'
- Sólo letras y dígitos
- ChallengeControllerTest
- ResourceHelperTest
Oracle Code Conventions for java: 9 - Naming Conventions
Google Java Style Guide: 5.2.2 class names
- UpperCamelCase
- Sólo letras y dígitos
- lowerCamelCase
- Sólo letras y dígitos
- isValidUUID
- initReactorHttpClient
Oracle Code Conventions for java: 9 - Naming Conventions
Google Java Style Guide: 5.2.3 method names
- lowerCamelCase
- Sólo letras y dígitos
- Terminar con '_test'
- getChallengeId_test
- findAll_test
Oracle Code Conventions for java: 9 - Naming Conventions
Google Java Style Guide: 5.2.3 method names
- Mayúsculas
- Sólo letras y dígitos
- Palabra separada con un solo guión bajo '_'
- static final int BEST_YEAR = 1977;
- static final String BEST_MONTH = "February";
Oracle Code Conventions for java: 9 - Naming Conventions
Google Java Style Guide: 5.2.4 constant names
- lowerCamelCase
- Comienza con letra
- Los nombres de las variables deben ser breves pero significativos.
- int year = 1977;
- static final String BEST_MONTH = "February";
Oracle Code Conventions for java: 9 - Naming Conventions
Google Java Style Guide: 5.2.4 constant names
- Only use for temporary "throwaway" variables
- Minúscula
- int => i, j, k, m and n
- char => c, d and e
Oracle Code Conventions for java: 9 - Naming Conventions
- Una sola letra mayúscula, opcionalmente seguida de un solo número
- Un nombre en la forma utilizada para las clases
- E, T, X, T2
- RequestT, ChallengeT
Google Java Style Guide: 5.2.8 Type variable names
- Sólo letras y dígitos
- UpperCamelCase
- Cada primera letra de cada palabra es letra mayúscula
- lowerCamelCase
- La primera letra de cada palabra está en minúscula, excepto la primera palabra que comienza
con una letra minúscula
- UpperCamelCase
- UserController
- ChallengeService
- lowerCamelCase
- creationDate
- validUUID
Google Java Style Guide: 5.3 Camel case defined
- 'java'
- 'org.springframework.boot' version '3.0.6'
- 'jacoco'
- 'org.sonarqube' version '4.0.0.2929'
-
BOOTSTRAP
- Versión 4.0.2
- group: 'org.springframework.cloud', name: 'spring-cloud-starter-bootstrap', version: '4.0.2'
-
COMMONS IO
- Versión 2.11.0
- 'commons-io:commons-io:2.11.0'
-
COMMONS LANG
- Versión 3.12.0
- 'org.apache.commons:commons-lang3:3.12.0'
-
COMMONS VALIDATOR
- Versión 1.7
- 'commons-validator:commons-validator:1.7'
-
CONSUL CONFIG
- Versión 4.0.2
- 'org.springframework.cloud:spring-cloud-starter-consul-config:4.0.2'
-
CONSUL DISCOVERY
- Versión 4.0.2
- 'org.springframework.cloud:spring-cloud-starter-consul-discovery:4.0.2'
-
PROJECTLOMBOK
- Versión 1.18.26
- 'org.projectlombok:lombok:1.18.26'
-
SPRING CONTEXT
- Versión 3
- 'org.springframework:spring-context:5.3.13'
-
SPRING BOOT AUTOCONFIGURE
- Versión 3.0.6
- 'org.springframework.boot:spring-boot-autoconfigure:3.0.6'
-
SPRING BOOT CLOUD COMMONS
- Versión 4.0.1
- 'org.springframework.cloud:spring-cloud-commons:4.0.1'
-
SPRING BOOT STARTER ACTUATOR
- Versión 3.0.6
- 'org.springframework.boot:spring-boot-starter-actuator:3.0.6'
-
SPRING BOOT STARTER DATA MONGODB
- Versión 3.0.6
- 'org.springframework.boot:spring-boot-starter-data-mongodb:3.0.6'
-
SPRING BOOT STARTER DATA MONGODB REACTIVE
- Versión 3.0.6
- 'org.springframework.boot:spring-boot-starter-data-mongodb-reactive:3.0.6'
-
SPRING BOOT STARTER WEB
- Versión 3.0.6
- 'org.springframework.boot:spring-boot-starter-web:3.0.6'
-
SPRING BOOT STARTER WEBFLUX
- Versión 3.0.6
- 'org.springframework.boot:spring-boot-starter-webflux:3.0.6'
-
SPRINGDOC OPENAPI
- Versión 2.1.0
- 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
- ASSERTJ
- Versión 3.24.2
- 'org.assertj:assertj-core:3.24.2'
- SPRING
- Versión 5.3.13
- 'org.springframework:spring-test:5.3.13'
- HAMCREST
- Versión 2.2
- 'org.hamcrest:hamcrest:2.2'
- JUNIT
- 'org.junit.jupiter:junit-jupiter'
- JUNIT JUPITER
- Versión 1.17.6
- 'org.testcontainers:junit-jupiter:1.17.6'
- JUNIT PLATAFORM SUITE
- Versión 1.8.1
- 'org.junit.platform:junit-platform-suite-engine:1.8.1'
- MOCKITO
- Versión 5.3.1
- 'org.mockito:mockito-core:5.3.1'
- MOCK WEBSERVER
- Versión 4.9.3
- 'com.squareup.okhttp3:mockwebserver:4.9.3'
- MONGODB
- Versión 1.17.6
- 'org.testcontainers:mongodb:1.17.6'
- PROJECT REACTOR
- Versión 3.1.0 Release
- 'io.projectreactor:reactor-test:3.1.0.RELEASE'
- SPRING BOOT STARTER TEST
- Versión 3.06
- 'org.springframework.boot:spring-boot-starter-test:3.0.6'
Los siguientes programas son requeridos para poder trabajar en el proyecto:
-
MongoDB: MongoDB es una base de datos NoSQL ampliamente utilizada en el desarrollo de aplicaciones. Se utiliza para almacenar y recuperar datos de forma eficiente. Puedes descargar MongoCompass desde la web oficial.
-
Postman: Postman es una herramienta que te permitirá probar y documentar las API de forma sencilla. Es especialmente útil para enviar solicitudes HTTP y verificar las respuestas. Puedes descargar Postman desde la web oficial.
-
Consul: Consul es una herramienta de descubrimiento y configuración de servicios. Se utiliza para gestionar la comunicación entre diferentes componentes de la aplicación. Puedes descargar Consul desde la web oficial.
-
Docker: Docker es una plataforma que permite empaquetar y distribuir aplicaciones en contenedores. Proporciona un entorno aislado para ejecutar la aplicación y sus dependencias. Puedes descargar Docker desde la web oficial.
-
Git: Git es un sistema de control de versiones distribuido ampliamente utilizado en el desarrollo de software. Te permitirá colaborar con otros desarrolladores y mantener un historial de cambios en el código fuente. Puedes descargar Git desde la web oficial.
-
Java SE Development Kit 17.0.7: Java SE Development Kit (JDK) es un conjunto de herramientas necesarias para desarrollar aplicaciones en Java. Asegúrate de tener instalada la versión 17.0.7 del JDK que es la que se usa en este proyecto. Puedes descargar JDK 17 desde la web oficial de Oracle.
-
Gradle 8.8
Es importante asegurarse de tener todas estas herramientas instaladas y configuradas correctamente antes de comenzar a trabajar en el proyecto.
Los siguientes programas son recomendables para facilitar el trabajo en el proyecto:
-
Mongo Tools: Mongo Tools es un conjunto de utilidades de línea de comandos para trabajar con MongoDB. Proporciona herramientas adicionales para importar y exportar datos, entre otras tareas. Puedes descargar MongoDB Command Line Database Tools desde la web oficial.
-
Mongo Shell: Mongo Shell es una interfaz de línea de comandos para MongoDB. Proporciona una forma interactiva de interactuar con la base de datos, ejecutar consultas y administrar colecciones. Puedes descargar MongoDB Shell desde la web oficial.
-
IntelliJ IDEA: IntelliJ IDEA es un entorno de desarrollo integrado (IDE) muy utilizado en el desarrollo de aplicaciones Java y otros lenguajes de programación. Puedes descargar IntelliJ IDEA desde la web oficial.
-
Plugin SonarLint para IntelliJ IDEA: SonarLint es una herramienta de análisis estático de código que te ayudará a identificar y corregir problemas de calidad en tu código. Es una ayuda útil para detectar Code Smell. Puedes obtener más información de SonarLint desde la web ofical de Jetbrains.
Recuerda que estos programas o plugins son recomendados, pero no son obligatorios. Utilizarlos puede mejorar tu productividad y la calidad del código, pero puedes optar por otras alternativas según tus preferencias y necesidades.
Hay una guía sobre testing en https://martinfowler.com/articles/practical-test-pyramid.html. Por favor, revísala antes de empezar el testing.