Skip to content

Contributing

Para ver o guia de contribuição em Português, clique aqui.

Contribution Guide

TLDR

This project uses poetry as the project manager.

poetry install

If your contribution involves code, please refer to the Style Guide. You can see all available commands in the environment here.

To check if everything is correct and the tests pass:

poetry run task test

To start the documentation:

poetry run task doc

If your change is visible to the users of the application, add an entry to the changelog:

towncrier create

The configurations are here.

Before submitting your pull request, make sure there's an issue. If not, create one first. The branch name should contain the issue number. For more information.

Environment Setup

If you need help setting up the development environment for this project, follow the instructions below.

Project Management

This project uses poetry (2.0.1) as the project manager. You can install it using pipx.

You can install it with:

pipx install poetry

In the project directory, run:

poetry install

This will install all project dependencies and the editable package.

Development Tools

A list of development tools and their configurations:

Taskrunner: taskipy

Taskipy makes it easier to run commands during the development process of the project:

pyproject.toml
65
66
67
68
69
70
71
72
73
74
75
[tool.ruff.format]
quote-style = "single"

[tool.taskipy.tasks]
format = 'ruff format'
lint = 'ruff check'
typos = 'typos videomaker_helper tests'
types = 'mypy videomaker_helper'
pre_test = 'task lint'
test = 'pytest --cov=videomaker_helper/ -vv -x'
stest = 'pytest'

You can use poetry run task --list to see all available commands:

$ poetry run task --list
format    ruff format
lint      ruff check
typos     typos videomaker_helper tests
types     mypy videomaker_helper
pre_test  task lint
test      pytest --cov=videomaker_helper/ -vv -x
post_test coverage html
doc       mkdocs serve

Below are some of the most common commands you can use:

poetry run task test    # Run the automated tests
poetry run task format  # Format the code
poetry run task typos   # Check the spelling in the code
...
Formatting and Linter: Ruff
pyproject.toml
52
53
54
55
56
57
58
59
60
61
62
63
pythonpath = "."
filterwarnings = 'ignore'

[tool.ruff]
line-length = 79

[tool.ruff.lint]
select = ['I', 'N', 'F', 'E', 'W', 'D', 'PL']
ignore = ['D100', 'D101', 'D103', 'D104', 'D203', 'D213', 'PLR0913']

[tool.ruff.lint.pydocstyle]
convention = "google"

For more details on style configuration, refer to the Style Guide.

To check for compliance, run:

poetry run task lint    # Check the project's style guide
poetry run task format  # Format the files
Static Type Checking: Mypy
pyproject.toml
76
77
post_test = 'coverage html'
doc = 'mkdocs serve'

To run type checks, execute:

poetry run task types
Spelling Check in Code: Typos

To run the spelling check, execute:

poetry run task typos
Changelogs with towncrier

All visible changes should add a fragment to the changelog.

The tags used follow the Keep a Changelog standard.

To add a new fragment:

towncrier create

Configuration:

pyproject.toml
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
[tool.mypy]
ignore_missing_imports = true

[tool.towncrier]
directory = "changelog.d"
filename = "CHANGELOG.md"
package = "videomaker_helper"
start_string = "<!-- towncrier release notes start -->\n"
underlines = ["", "", ""]
title_format = "## [{version}](https://github.com/dunossauro/videomaker-helper/tree/{version}) - {project_date}"
issue_format = "[#{issue}](https://github.com/dunossauro/videomaker-helper/issues/{issue})"

[[tool.towncrier.type]]
directory = "security"
name = "Security"
showcontent = true

[[tool.towncrier.type]]
directory = "removed"
name = "Removed"
showcontent = true

[[tool.towncrier.type]]
directory = "deprecated"
name = "Deprecated"
showcontent = true

[[tool.towncrier.type]]
directory = "added"
name = "Added"
showcontent = true

[[tool.towncrier.type]]
directory = "changed"
name = "Changed"
showcontent = true

[[tool.towncrier.type]]
directory = "fixed"

Style Guide

This project follows the style guides:

To check code style, run:

poetry run task lint

Versioning and Git

There is no predefined format for commit messages. Feel free to choose a style that makes sense. Here are a few things to keep in mind:

  • All PRs must have an issue. If you want to contribute something that doesn’t have an issue yet, create one before submitting.
  • PRs must be submitted to the development branch.
  • The branch name must start with the issue number:
    • For example, if the issue number is 42, the branch name would be 42_short-description, where 'short-description' is a brief summary of the change.
  • To notify others you're starting a contribution and allow them to track progress, open a draft PR and link the relevant issue.:
    • Once the changes are ready, you can mark the PR as "Ready for review."

Changelogs

All visible changes to the users of the application should be documented in the changelog. This helps maintain a clear history of changes and ensures users are aware of updates.

After making a change, if it is visible to the application's users, add an entry to the changelog using towncrier:

towncrier create

Continuous Integration

This project uses GitHub Actions for Continuous Integration (CI). If you need to run the entire process locally, you can use act:

act

act is a tool that emulates GitHub Actions workflows locally, allowing you to run tests and CI processes without needing to push to the repository.

The full CI configuration can be found in .github/workflows/pipeline.yaml

Guia de contribuição

TLDR

O projeto usa o poetry como gerenciador de projeto.

poetry install

Se sua contribuição envolver código, consulte o Guia de estilo. Você pode ver todos os comandos disponíveis no ambiente aqui.

Para checar se tudo está correto e os testes passam:

poetry run task test

Para iniciar a documentação:

poetry run task doc

Caso sua alteração seja visível a quem for usar a aplicação, adicione uma entrada ao changelog:

towncrier create

As configurações estão aqui.

Antes de enviar seu pull request, garanta que exista uma issue, se não houver uma, crie antes de submeter, o nome da branch deve conter o número da issue. Caso precise de mais informações.

Configuração do ambiente

Se você precisar de ajuda para configurar o ambiente de desenvolvimento deste projeto, siga as instruções abaixo.

Gerenciamento de projeto

Esse projeto usa o poetry (2.0.1) como gerenciador de projeto. Você pode instalar ele com pipx.

Você pode instalar com:

pipx install poetry

No diretório do projeto, execute:

poetry install

para instalar todas as dependências do projeto e o pacote editável.

Ferramentas de desenvolvimento

Uma lista das ferramentas de desenvolvimento e suas configurações:

Taskrunner: taskipy

O taskipy facilita a execução dos comandos durante o momento de desenvolvimento do projeto:

pyproject.toml
65
66
67
68
69
70
71
72
73
74
75
[tool.ruff.format]
quote-style = "single"

[tool.taskipy.tasks]
format = 'ruff format'
lint = 'ruff check'
typos = 'typos videomaker_helper tests'
types = 'mypy videomaker_helper'
pre_test = 'task lint'
test = 'pytest --cov=videomaker_helper/ -vv -x'
stest = 'pytest'

Você pode usar poetry run task --list para ver todos os comandos disponíveis:

$ poetry run task --list
format    ruff format
lint      ruff check
typos     typos videomaker_helper tests
types     mypy videomaker_helper
pre_test  task lint
test      pytest --cov=videomaker_helper/ -vv -x
post_test coverage html
doc       mkdocs serve

Abaixo estão alguns dos comandos mais comuns que você pode utilizar:

poetry run task test    # Executa os testes automatizados
poetry run task format  # Executa a formatação do código
poetry run task typos   # Checa a grafia do código
...
Formatação e linter: Ruff
pyproject.toml
52
53
54
55
56
57
58
59
60
61
62
63
pythonpath = "."
filterwarnings = 'ignore'

[tool.ruff]
line-length = 79

[tool.ruff.lint]
select = ['I', 'N', 'F', 'E', 'W', 'D', 'PL']
ignore = ['D100', 'D101', 'D103', 'D104', 'D203', 'D213', 'PLR0913']

[tool.ruff.lint.pydocstyle]
convention = "google"

Para mais detalhes sobre a configuração do estilo, consulte o Guia de estilo.

Basicamente para executar a checagem você deve executar:

poetry run task lint    # Checa o guia de estilo do projeto
poetry run task format  # Formata os arquivos
Checagem de tipos estáticos: Mypy
pyproject.toml
76
77
post_test = 'coverage html'
doc = 'mkdocs serve'

Para executar a checagem de tipos você pode executar:

poetry run task types
Checagem de erros de grafia no código: Typos

Para executar a checagem de erros de grafia você pode executar:

poetry run task typos
Changelogs com towncrier

Todas as alterações visíveis devem adicionar um fragmento ao changelog.

As tags usadas seguem o padrão Keep a changelook.

Para adicionar um novo fragmento:

towncrier create

Configuração:

pyproject.toml
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
[tool.mypy]
ignore_missing_imports = true

[tool.towncrier]
directory = "changelog.d"
filename = "CHANGELOG.md"
package = "videomaker_helper"
start_string = "<!-- towncrier release notes start -->\n"
underlines = ["", "", ""]
title_format = "## [{version}](https://github.com/dunossauro/videomaker-helper/tree/{version}) - {project_date}"
issue_format = "[#{issue}](https://github.com/dunossauro/videomaker-helper/issues/{issue})"

[[tool.towncrier.type]]
directory = "security"
name = "Security"
showcontent = true

[[tool.towncrier.type]]
directory = "removed"
name = "Removed"
showcontent = true

[[tool.towncrier.type]]
directory = "deprecated"
name = "Deprecated"
showcontent = true

[[tool.towncrier.type]]
directory = "added"
name = "Added"
showcontent = true

[[tool.towncrier.type]]
directory = "changed"
name = "Changed"
showcontent = true

[[tool.towncrier.type]]
directory = "fixed"

Guia de estilo

Esse projeto segue os guias de estilo:

Para checar a conformidade do código você pode executar:

poetry run task lint

Versionamento e git

Para enviar sua contribuição, não há um formato pré-definido para as mensagens de commit. Sinta-se à vontade para escolher um estilo que faça sentido. Somente alguns pontos para atenção:

  • Todos os PRs enviados devem ter uma issue, caso você queira contribuir com algo que ainda não tem issue, abra uma issue antes.
  • As solicitações de PR devem ser enviadas para branch development.
  • O nome da branch deve iniciar com o número da issue
    • Por exemplo, se a issue for número 42, o nome da branch seria 42_texto, onde 'texto' é uma descrição curta da mudança.
  • Para notificar que você está começando uma contribuição e permitir que outros saibam, abra um PR como 'draft' e vincule a issue relevante:
    • Ao finalizar as alterações você pode clicar em "Ready for review"

Changelogs

Todas as alterações visíveis para os usuários da aplicação devem ser documentadas no changelog. Isso ajuda a manter um histórico claro das mudanças feitas e garante que os usuários estejam cientes das atualizações.

Após a alteração, caso ela seja visível para quem usa aplicação adicione uma entrada no changelog usando o towncrier:

towncrier create

Integração contínua

Este projeto utiliza o GitHub Actions para realizar a Integração Contínua (CI). Se precisar executar todo o fluxo localmente você pode usar o act:

act

O act é uma ferramenta que emula os workflows do GitHub Actions localmente, permitindo que você execute testes e processos de integração contínua sem precisar fazer push para o repositório.

A configuração completa do CI pode ser encontrada em .github/workflows/pipeline.yaml