# GUIA DE CONTRIBUIÇÃO PARA OS SCRIPTS DO SENIOR CI

O projeto está em migração para python, logo novas funcionalidades devem estar escritas em python, podendo já utilizar os padrões já existentes.

## Configuração de ambiente dev

1.  Instale e configure o [Docker](https://www.docker.com/get-started) em seu sistema operacional;
2.  Instale o [VS Code](https://code.visualstudio.com) ou [VS Code Insiders](https://code.visualstudio.com/insiders);
3.  Instale as extensões do VS Code:
    *   [Dev Containers](vscode:extension/ms-vscode-remote.remote-containers);
    *   [SonarLint](vscode:extension/SonarSource.sonarlint-vscode);
4.  [Configure a conexão](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarlint-vscode#connected-mode) com o SonarQube da Senior (https://sonar.senior.com.br) e com o Nome da Conexão como "SonarQubeSenior";
5.  Abra o projeto e aparecerá uma mensagem com o botão **Reopen in container**, aperte-o; <br/>
    Você também pode executar o comando **Remote-Containers: Reopen in container** via F1;
6.  Basta aguardar o ambiente ser inicializado e configurado. :blue_heart:

## Processo de Merge Request

Para realizar melhorias ou ajustes nos scripts utilizados na integração contínua dos produtos é necessário seguir os seguintes passos:

 - Criar um branch no projeto Senior CI a partir da `master`, no padrão de nomenclatura Senior (e.g.
   `feature/jira-1234`).
 - Realizar as implementações necessárias para o sua melhoria no branch recém criado.
 - Testar a melhoria em seu projeto que necessita da alteração. (Informações de como testar logo a seguir)
 - Resolver todas as issues apontadas pelo SonarQube no seu Merge Request.
 - Abrir uma issue no Jira para o time DevOps (projeto **DEVOPS** no Jira) solicitando a revisão do Merge Request e a liberação de uma nova versão oficial do Senior CI. Na descrição da issue **deve ser informado o motivo da alteração**, para que possamos entender o contexto (lembrando sempre que deve ser uma alteração que traga melhorias para **todos os outros times de desenvolvimento** e não só da sua equipe).
 - Abrir um Merge Request no Senior CI associado à tarefa no Jira, esta tarefa serve como alerta para a equipe para analisar a alteração e realizar o aceite do merge e a liberação de uma nova versão do Senior CI.

## Como testar as alterações no seu projeto?

Para testar as alterações em um projeto isolado sem impactar nos demais projetos basta adicionar a variável `SCI_VERSION` nas configurações do seu **projeto** no  GitLab (`Settings > CI / CD > Variables`), informando como valor da variável o nome do branch criado no repositório Senior CI com as suas alterações. Desse modo o CI irá utilizar os scripts do branch com a sua implementação na execução de um novo Job do seu projeto.

> Ao finalizar as alterações e ser realizado o aceite do Merge Request é importante que a variável `SCI_VERSION` sejam removidas das configurações do **projeto**. Quando o Merge Request for aceito o branch da implementação será excluído e caso a variável não tenham sido removidas ocorrerão erros em **todos os jobs do CI** executados no projeto em questão.

***
## 📦 Migrando seu script para o senior-ci

Esta documentação tem como objetivo orientar a migração de scripts .sh e scripts Python legados para o modelo de CI baseado no padrão de projeto Abstract Factory com fluxos padronizados.

### 📁 Estrutura Base do Projeto

Todos os projetos devem seguir a estrutura definida em senior-ci, respeitando os padrões abaixo:

Diretório Principal: src/

Este é o diretório onde toda a lógica de abstração, controle e execução deve estar contida.

***
### 🔢 1. Definindo o Tipo de Projeto
***

No arquivo src/enun/project_type.py:

Adicione uma nova enum representando o seu projeto:

```
class ProjectType(Enum):
    PYTHON_APP = "20"
    PYTHON_LIB = "21"
```

### ⚠️ Importante: verifique se a enum já existe antes de adicionar uma nova.

***
### 🧩 2. Criando a Interface do Projeto
***

No diretório src/interface:

Crie uma interface estendendo ProjectInterface.
Esta interface é responsável por sobrescrever/criar comportamentos específicos do seu projeto.

```
from src.interface.project_interface import ProjectInterface

class PythonProjectInterface(ProjectInterface):
    def compile(self):
        # lógica específica para compile
        pass

    def sonar_scanner(self):
        # lógica específica para sonar_scanner
        pass

    def novo_comportamento(self):
        # lógica para o novo comportamento
        pass
```

***
### 🧠 3. Criando o Controller
***

No diretório src/controller:

Crie o controller do seu projeto, estendendo a interface criada acima.
Este controller é o responsável por executar as operações reais.

```
from src.interface.python_project_interface import PythonProjectInterface

class PythonLibController(PythonProjectInterface):
    def build(self):
        print("Build da lib python...")
        novo_comportamento()
        super().build()

    def test(self):
        print("Executando testes...")
```
***
### 🚀 4. Registro do Controller
***

No arquivo src/main/__init__.py:

Adicione um if que instancie o controller conforme a enum definida.

```
from src.enun.project_type import ProjectType
from src.controller.python_lib_controller import PythonLibController

def get_project_controller_by_type():
    sci_project_type = get_env_variable_required("SCI_PROJECT_TYPE")
    project = None

    if sci_project_type == ProjectType.PYTHON_LIB:
        project = PythonLibController()

    return project
```

    # Adicione outras condições conforme necessário

***
### 🛠️ 5. Configurações no GitLab
***

No repositório do seu projeto no GitLab:

✅ Defina as variáveis de ambiente:
```
SCI_VERSION	= Nome da branch (devops-4412)
SCI_PROJECT_TYPE = Tipo do projeto, conforme a enum (PYTHON_LIB)
```

> Importante: O processo de review é notificado via email enviado pelo próprio gitlab


***
### 🧪 6. Ativando o Semantic Release
***

Consulte a definição completa em:

🔗 [Semantic Release](https://wiki.senior.com.br/pt-br/DevSecOps/Semantic-Release)

✅ Atualize o seu .gitlab-ci.yml com o modelo padrão, incluindo `flow/release/semantic.gitlab-ci.yml`:

```
stages:
  - validate
  - generate
  - compile
  - report
  - sast
  - pre-release
  - release
  - delivery
  - publish
  - deploy

include:
  project: $SCI_PROJECT_TEMPLATES
  file:
    - flow/validate/complete.gitlab-ci.yml
    - flow/release/complete.gitlab-ci.yml
    - flow/release/semantic.gitlab-ci.yml
    - flow/deploy/prod.gitlab-ci.yml
  ref: $SCI_TEMPLATE_VERSION
```

## 🔁 Estágios do Pipeline no senior-ci
A seguir está uma visão geral dos estágios do pipeline padrão do senior-ci, com explicações claras sobre suas responsabilidades e quando (ou se) você precisa adicionar código específico para seu projeto.

Consulte a definição completa dos fluxos em:

🔗 [Fluxos CI/CD]('https://wiki.senior.com.br/pt-br/DevSecOps/Fluxos-CI-CD')

***
1. VALIDATE – 🔍 Validação de Qualidade e Padrões
> Objetivo: Validar o código-fonte com ferramentas de qualidade estática.

Ferramentas utilizadas: cqat, black, ruff, etc.

Também pode incluir validações de formato, dependências e lint.


***
2. GENERATE – 🛠️ Geração de Código (Opcional)
> Objetivo: Etapa para gerar código automaticamente, se necessário.

Ex: geração dos .class do java

Python: Usado em projetos que fazem codegen, como APIs com FastAPI + Pydantic + OpenAPI.

***
3. COMPILE – 🧱 Build do Projeto
> Objetivo: Compilar ou preparar o build da aplicação.

Exemplo de uso: docker build de imagem docker ou artefatos com whl ou outros formatos.

Artefatos gerados aqui podem ser usados em outras fases do pipeline.

***
4. REPORT – 📊 Geração de Relatórios
> Objetivo: Executar testes e ferramentas que geram relatórios.

Ferramentas comuns: pytest, trivy, cobertura de testes, junit, etc.

Relatórios gerados aqui podem ser usados em outras fases do pipeline ou integrados ao GitLab.


***
5. SAST – 🛡️ Análise de Segurança
> Objetivo: Análises de segurança profunda no código-fonte.

Ferramentas: SonarQube, DefectDojo.

Reporta vulnerabilidades e práticas inseguras no código.

***
6. PRE-RELEASE – 📦 Preparação da Versão
> Objetivo: Pré-validação para garantir que tudo está pronto para o release.

Pode envolver checks de versão, dependências, mudanças pendentes e geração de versão snapshot.

Geralmente automático, mas pode ser customizado se necessário, atraves da variável
`SCI_MANUAL_RELEASE` com o valor true.

***
7. RELEASE – 🚀 Geração de Versão (Semantic Release)
> Objetivo: Automatizar o versionamento baseado nos commits (semantic-release).

A versão é gerada com base em commits do tipo feat, fix, BREAKING CHANGE, etc.

Tags são criadas automaticamente.

Geralmente automático, mas pode ser customizado se necessário, atraves da variável
`SCI_MANUAL_RELEASE` com o valor true.

***
8. DELIVERY – ♻️ Entrega (para Hotfixes ou Releases Manuais)
> Objetivo: Tratar entregas específicas, como hotfixes, em pipelines separados.

Normalmente usado em estratégias Git Flow.

Pode ser omitido se não usar esse modelo.

***
9. PUBLISH – 📤 Publicação de Artefatos
> Objetivo: Publicar o projeto em repositórios como DockerHub, Artifactory, PyPI, etc.

Para apps Docker, é onde sobe a imagem para o registry.

***
10. DEPLOY – ☁️ Deploy para Ambiente
> Objetivo: Realizar o deploy da aplicação em ambientes (dev, staging, prod).

Pode incluir scripts para Kubernetes, Helm, Terraform.

***
### ✅ Resumo dos Estágios para Projetos Python

| Estágio       | Código Customizado? | Descrição                                                                          |
|:------------- |:--------------------|:---------------------------------------------------------------------------------- |
| `validate`    | ⚠️ Opcional         | Linters, análise estática e ferramentas de qualidade como `black`, `ruff`, `cqat`. |
| `generate`    | ⚠️ Opcional         | Usado somente se houver geração automática de código .                             |
| `compile`     | ⚠️ Opcional         | Para builds de imagem Docker ou artefatos binários, se necessário.                 |
| `report`      | ❌ Não              | Execução de testes unitários, cobertura de código, Trivy, geração de relatórios.   |
| `sast`        | ❌ Não              | Integração com ferramentas de análise de segurança como SonarQube ou Bandit.       |
| `pre-release` | ⚠️ Opcional         | Geração de versão snapshot.                                                        |
| `release`     | ⚠️ Opcional         | Geração automática de versão via Semantic Release com base nos commits.            |
| `delivery`    | ⚠️ Opcional         | Utilizado em casos específicos como hotfixes (estratégia Git Flow).                |
| `publish`     | ⚠️ Opcional         | Empacotamento e publicação em DockerHub, PyPI, etc.                                |
| `deploy`      | ⚠️ Opcional         | Executa deploys automatizados via scripts, Docker, K8s ou outros.                  |

### Testando alterações de projetos Python

Após efetuar alterações em qualquer parte que afete projetos Python, deve-se validar o funcionamento de todos os tipos.
Para isso, pode-se utilizar como base a seguinte lista, com seu tipo e projetos de exemplo:

1. PYTHON_LIB
    - Projetos que são bibliotecas Python;
    - Exemplo de projeto: [sdp-spark](https://git.senior.com.br/data-platform/sdp-spark);

2. PYTHON_APP_DPSI
    - Projetos que utilizam o DPSI, normalmente ficam localizados no grupo `data-platform-products`;
    - Exemplo de projeto: [novasoft-dpsi-config](https://git.senior.com.br/data-platform-products/novasoft-dpsi-config);

3. PYTHON_APP_SDP
    - Projetos de pipeline que seguem o padrão do SDP. Normalmente possuem no nome o sufixo `-pipeline`;
    - Exemplo de projeto: [openmetadata-ingestion-pipeline](https://git.senior.com.br/data-platform/openmetadata-ingestion-pipeline);

4. PYTHON_GENERIC
    - Projetos que não seguem um padrão específico;
    - Projetos que contém, por exemplo, o desenvolvimento de API REST;
    - Estes projetos precisam que seus fontes fiquem localizados na pasta `src`;
    - Exemplo de projeto: [python-flex-poc](https://git.senior.com.br/data-platform/python-flex-poc);

5. PYTHON_APP
    - Descontinuado, portanto, não deve ser utilizado;

> Em caso de problemas ou dúvidas, favor consultar a equipe do Data Office (ARQDAT).