Installation and development
Para poder empezar a desarrollar primero deberas instalar las herramientas necesarias. Las herrmientas que necesitas son las siguientes:
- Git
- STM32CubeIDE
- STM32CubeProgrammer
- Visual Studio
- Github
- Trello
Como herramienta de control de versiones usamos git. Esta herramienta es ampliamnete usada y problemente ya conozcas como funciona. Si no es el caso se recomienda aprender el funcionamiento básico a traves de algun tutorial.
Git se puede descargar a través del siguiente enlace.
Como IDE de desarrollo principal del código a más bajo nivel como por ejemplo la HALAL usamos STM32CubeIDE que es el IDE que proporciona ST para facilitar la programación de sus microcontroladoes.
Usamos la siguiente versión:
Version: 1.10.1
Build: 12716_20220707_0928 (UTC)
Es importante tener la misma versión para evitar problemas de compatibilidad. Si se actualizase a una versión posterior se avisaria a todos los desarrolladores.
Podemos descargar esta herramienta desde el siguiente enlace. Una vez en estemos en la página elegiremos la version indicada. La página pedira que introducas tu correo electronico y te mandara el enlace de descarga a este.
STM32CubeProgrammer es una herramienta muy útil que nos permite programar los micros sin tener que usar el STM32CubeIDE y nos permite observar y manipular la memoria del microcontrolador.
Se puede descargar desde el siguiente enlace. Los pasos a seguir son los mismos que en la herrmienta anterior.
Visual Studio es el IDE que utilizamos para el desarrollo del código de más alto nivel de la libreria. Esta herramienta es ampliamente conocida y relativamente fácil de usar.
Se puede descargar del siguiente enlace. Si eres estudiante de la UPV puedes utilizar la cuenta microsoft que proporciona la universidad para obtener la versión profesional, aunque la gratuita es mas que suficiente.
Como repositorio online para git utilizamos github. Si estas leyendo esto no necesitas más información ;).
Trello es una herrmienta online, aunque se puede descargar como aplicación, que nos permite mantener el siguimiento de las tareas que se estan realizando.
Se puede acceder a traves del siguiente enlace. Una vez dentro tan solo deberas registrate y solicitar acceso al trello de equipo.
Antes de empezar a desarrollar es importante que conozcas cual es nuestra metodologia a la hora de usar git y github. Hay tres aspectos imporantes en el uso de nuestro repositorio. La primera y más importante es nuestra organizacion de las ramas y funcionamiento de los pull request, otros aspectos importantes son las issues y la wiki del repo. A continuación se explicaran estos tres aspectos.
Seguimos un gitflow relativamente standard. La rama main representa el release estable actual, de esta rama parte la rama development que representa la versión de desarrollo estable actual, a su vez de esta parten dos ramas más (alemenos por ahora) que son HALAL y STLIB_LOW. Estas dos ramas reprensentan el estado actual de desarrollo.
Estas son las ramas principales del repositorio. Estas ramas se encuentran protegidas y solo se les puede hacer merge a traves de pull request y estas deben ser aceptadas por almenos dos desarrolladores distintos al que ha desarrollado el código a mergear. De esta forma nos aseguramos que el código que se va a subir es código de cálidad.
Todas las nuevas caracteristicas nuevas que se quieran implementar deben partir o bien de la rama HALAL o de la rama STLIB_LOW. Las ramas deben reprensentar caracteristicas concretas y de tamaño pequeño o mediano. Si una tarea es compleja y requiere mucho código se debe repartir en varias ramas. Estas ramas deben seguir la siguiente convencion de nombre: features/<feture-name> por ejemplo features/Flash.
gitGraph
checkout main
commit id: "1 Initial commit"
commit id: "2 New branch"
branch development
commit id: "3 New branch"
branch HALAL
commit id: "4 New branch"
checkout HALAL
branch features/Flash
checkout features/Flash
commit id: "6 Read flash finished"
commit id: "8 Write and tests"
checkout HALAL
merge features/Flash
checkout development
merge HALAL
checkout main
merge development
Una vez terminemos de desarrollar la caracteristica en la rama correspondiente debemos hacer un pull request para poder subir este código a la rama principal correspondiente, por ejemplo si estubieses haciendo el servicio de la memoria flash como en el ejemplo anterior harias pull request de features/Flash -> HALAL.
Los pull request deben seguir una estructura estandard para facilitar la interpretación de estos. Pueden contener los siguientes puntos:
- Explicación de la caracteristica
- Ejemplos de uso
- Tests que se han pasado
- Notas y/o advertencias
Como minimo un pull request debe contener el punto 1 y 3. Dependiendo de la complejidad de la caracteristica será muy recomendable añadir ejemplos de uso. Como ejemplo de pull request minimo (explicacion y tests) se puede ver en el siguiente enlace (el apartado documentacion y error handler en este caso contarian como parte de la explicación aunque no es necesario añadirlo).
Existen dos tipos de pull request, los normales y los draft pull request. Los primeros en cuanto son publicados pasan a la espera de ser revisados y aprobados. Los segundos son interesantes porque sirven para cuando la rama aun esta en desarrollo o le faltan por pasar los tests pero quieres que otros desarrolladores las puedan ir revisando para recivir feedback sin que puede ser aceptada hasta que lo indiques. El tipo de pull request se puede elegir dandole a la flecha al lado de la opcion de crear el pull request.
Antes de crear el pull request es tambien importante añadir como reviewers y assignees a todos los desarrolladores para que el bot de Slack los notifique. También debes añadir las labels y la milestones correspondientes.
Una vez tu pull request haya sido aceptado ya podras hacer merge. Finalmente si no se trataba de una caracteristica muy importante es recomendable borrar la rama.
Las issues son un aspecto importante en el desarrollo
❗ Do not upload your local config files ❗ Before you start developing, use this commands to tell git that you don't want to update the standard configuration files:
git update-index --skip-worktree .\.cproject
git update-index --skip-worktree .\.settings\
It may also be necesary to ignore other files, in this case it is as simple as using the same command but specifying the path to the folder or file that you want to ignore.
If you want to undo this, just do:
git update-index --no-skip-worktree .\.cproject
git update-index --no-skip-worktree .\.settings\
