Typedoc + Angular + Bitbucket

La verdad es que escribir código es algo increíble. Es de las pocas formas en las que podemos crear algo nuevo e incluso cambiar el mundo desde nuestra silla con una computadora. Ahora bien, con la evolución de la industria cada día necesitamos hacerlo mejor y más rápido. Es allí cuando debemos recurrir a la automatización y conceptos como CI/CD (Continuos Integration / Continuos Deployment) toman peso.

Como resultado de estas necesidades Atlassian ha implementado Pipelines en su producto Bitbucket por lo que reciben el nombre de ¨Bitbucket Pipelines¨ (si, no lo pensaron demasiado).

Como comente en mi artículo anterior (Git Hooks ¿Qué son y para que?), llevo desde marzo 2020 trabajando como freelance para una empresa y pues parte la aventura que empezó como una asesoría, hoy me ha llevado al área de DevOps y a crear estas integraciones para que el equipo de desarrollo funcione de forma más eficiente.

El ejemplo que les explicaré hoy es un proyecto de Angular el cual hemos integrado a Firebase Hosting con nuestro flujo de ramas basado en GitFlow.

Lo primero que explicaré es como creamos nuestra documentación de forma automática mediante Typedoc

Typedoc

Es una librería destinada para proyectos de TypeScript la cual nos permite generar una documentación desde los comentarios del código. Si bien es un poco cansado poner comentarios en nuestro código, la verdad es que cuando la aplicación llega a cierto punto de crecimiento se vuelve una necesidad.

El uso es simple, necesitamos crear un archivo en la raiz de nuestro proyecto que tenga la configuración con la que crearemos nuestra documentación. Algo así:

{
    "out": "docs",
    "tsconfig": "./tsconfig.app.json",
    "theme": "./node_modules/typedoc-bitbucket-theme/dist/",
    "plugin": "typedoc-plugin-markdown",
    "exclude": "**/*+(index|.spec|.e2e).ts",
    "inputFiles": ["./src"]
}

En este caso específicamente estamos usando un tema o plantilla para bitbucket y un plugin que genera los archivos en formato Markdown. De igual manera estamos excluyendo a los test que se crean para los componentes de Angular y estamos setteando la configuración del TypeScript desde nuestro tsconfig.app.json para que reconozca algunos ajustes que hemos hecho. Por último vemos que se coloca una lista con los directorios desde los que leerá los archivos y un dato para el nombre nombre del directorio en el que creara la documentación.

Para ejecutarlo solamente debemos correr el siguiente comando:

npx typedoc

Ambientes

En este escenario trabajamos con 4 ambientes los cuales teníamos que configurar previamente en el proyecto.

• Develop
• Staging
• SandBox
• Production

Para el uso de estos despliegues necesitamos un token de Firebase CLI que podremos generar con el comando

firebase login:ci

Tipos de Pipelines

En este caso hemos implementado 2 tipos de pipelines, uno basado en la creación/actualización de los PullRequest y uno en el merge de las ramas. Para esto usamos una rama por ambiente y una rama por cada tarea de desarrollo que se realiza.

Algo importante antes de entrar en estas configuraciones son 2 llaves que usaremos debemos agregar:

• $FIREBASE_TOKEN: Token generado con el comando anterior.
• $SENTRY_TOKEN: Token de autenticación creado en Sentry.

Por PullRequest

En este caso buscamos utilizar los nuevos canales de pruebas que nos ofrece Firebase Hosting. Por lo que debemos agregar la configuración al archivo bitbucket-pipelins.yml de la siguiente manera:

image: node:12.12.0

pipelines:
  pull-requests:
    "**": #this runs as default for any branch not elsewhere defined
      - step:
          name: PullRequest
          caches:
            - node
          script:
            - npm install --quiet
                         - npm run build:$BITBUCKET_PR_DESTINATION_BRANCH
                         - npx firebase use <project_id>
                         - npx firebase hosting:channel:deploy --token "$FIREBASE_TOKEN" "$BITBUCKET_PR_ID"

Para está configuración vamos a utilizar 2 variables que nos provee de forma automática el ambiente de ¨Bitbucket Pipelines¨ que son:

• $BITBUCKET_PR_DESTINATION_BRANCH: Nombre de la rama a la que se quieren unir los cambios.
• $BITBUCKET_PR_ID: El Id numérico del PullRequest creado por BitBucket.

Por Merge

Ahora bien en el caso de que un cambio es aprobado y unido al código de la aplicación de forma definitiva, procedemos a realizar una compilación basada en el ambiente que corresponde pero, en está ocasión la diferencia está en las ramas main y develop las cuales realizan algunos pasos extras.

Staging y SandBox

image: node:12.12.0

pipelines:
  branches:
    staging:
      - step:
          name: Deploy to staging
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:$BITBUCKET_PR_DESTINATION_BRANCH
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to hosting from Pipeline"

Develop

En este caso usamos TypeDoc para generar la documentación y después actualizamos la wiki del repositorio mediante un push de git. Para este proceso necesitamos los siguientes parámetros:

• $AUTH_USER: El nombre de usuario que tengamos en BitBucket.
• $AUTH_PASSWORD: La contraseña del usuario correspondiente.
• $AUTH_NAME: Nombre que el usuario utilizará para realizar el commit.
• $AUTH_EMAIL: Correo Electrónico que utiliza el usuario.

image: node:12.12.0

pipelines:
  branches:
    develop:
      - step:
          name: Deploy to Development
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:develop
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to development from Pipeline"
      - step:
          name: Doc generation
          caches:
            - node
          script:
            - npm install --quiet
            - rm -rf docs/ && npx typedoc
            - rm -rf docs/modules && rm -rf docs/interfaces && rm docs/README.md
            - rm -rf wiki && git clone https://$AUTH_USER:$AUTH_PASSWORD@bitbucket.org/<project>/<repository>.git/wiki
            - cp -r docs/* wiki/.
            - cd wiki && git config user.name "$AUTH_NAME" && git config user.email "$AUTH_EMAIL" && git add * && git commit -m "Updating the wiki autogenerated" && git push origin master
            - cd ..
            - rm -rf wiki && rm -rf docs
            - ls

Main

En este último caso realizamos 3 procesos, el primero es la publicación de la nueva versión del sitio en nuestro hosting con la configuración de producción y después de forma paralela realizamos 2 acciones.

1. Crear una tag: Esto lo hacemos basados en la versión que obtenemos del archivo package.json del proyecto en cuestión.
2. Crear un release en Sentry: En nuestro caso utilizamos Sentry, ya que aún no contamos con Firebase Crashlytics para web.

image: node:12.12.0

pipelines:
  branches:
        main:
      - step:
          name: Deploy to Firebase Hosting Prod
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:prod
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to Prod from Pipeline"
      - parallel:
          - step:
              name: Create Tag
              caches:
                - node
              script:
                - npm install
                - git tag -a $(npx pkg-jq -r .version) -m "Tagged on deployment"
                - git push origin --tags
          - step:
              name: Release on Sentry
              caches:
                - node
              script:
                - pipe: sentryio/sentry-new-release:0.3.0
                  variables:
                    SENTRY_AUTH_TOKEN: $SENTRY_TOKEN
                    SENTRY_ORG: "<sentry_org>"
                    SENTRY_PROJECT: "<sentry_project_id>"

Si deseas saber más de mi puedes visitar mi página: https://fjbatresv.com/