checklist-pt-br.md

1. Conceitos

• Verifique se seu app segue a filosofia Unix: "Faça uma coisa, e faça bem";
• Verifique se a descrição do seu app encaixa em poucas palavras. Exemplos:
  • django-taggit: django-taggit a simpler approach to tagging with Django;
  • django-js-reverse: Javascript URL handling for Django that doesn't hurt;
  • django-impersonate: Simple application to allow superusers to "impersonate" other non-superuser accounts.
• Verifique se a descrição do seu app tem a palavra "e", e caso tenha, tente quebrar em mais aplicações.

2. Fácil para Instalar

• Crie um arquivo LICENSE;
• Distribua no PyPI:
  • Nome com prefixo django-;
  • Cheque conflito de nomes;
  • Mau exemplo de django-filter vs django-filters;
  • Use Wheels.
• Publique em Django Packages;
• Instale dependências automaticamente:
  • Adicione dependências em install_requires no setup.py;
  • Não adicione Django em install_requires;
  • Não coloque versões com == em install_requires. Use >=.
• Verifique se você precisa de uma aplicação Django ou um pacote Python regular;
• Aplicações Django precisam ser adicionados em INSTALLED_APPS. Pacotes python não;
• Exemplos de pacotes Python:
  • django-templated-email.
  • django-hashid-field.
  • django-downloadview.
• Tenha padrões sensatos e inteligentes:
  • Torne-o um padrão;
  • Não obrigue copiar e colar de trechos de código;
  • Não faça nada perigoso por padrão, como caching.
• Exija que o comportamento inseguro seja explícito:
  • Não exiba tudo se algo não estiver definido, exemplo: fields = None não deve significar todos os campos.
• Tenha propriedades declarativas para habilitar uma fácil configuração:
  • Adicione um prefixo para todas as propriedades da aplicação, como MYAPP_SETTING_KEY;
  • Converta parâmetros internos hardcoded para propriedades:
    • Por exemplo, AVATAR_MAX_SIZE do django-avatar deve ser hardcoded, mas ele é uma configuração;
    • Se é necessário frequentemente por desenvolvedores, habilite o comportamento para ser alterado com somente uma alteração na configuração;
    • Se é necessário frequentemente por desenvolvedores, aceite classes customizadas e funções nas configurações via dotted path;
      • Por exemplo, django-taggit suporta tag parsers customizados via configuração.
• Suporte pipelines declarativos para workflows configuráveis;
• Cheque a implementação de python-social-auth;
• Providencie views padronizados com templates e URLs para habilitar a aplicação para ser incluída facilmente;
• Tenha uma política de upgrade amigável:
  • Torne deprecated antes de remover. Para raise deprecation warnings, use o módulo warnings do Python.
  • Não reescreva migrações:
    • Os usuários podem depender dos seus antigos arquivos de migração, porque eles rodaram no passado.
  • Mantenha um CHANGELOG;
  • Siga o Versionamento Semântico;
• Dê créditos, tenha um arquivo AUTHORS:
  • Verifique este script para gerar um arquivo AUTHORS a partir do histórico do seu repositório GIT.

3. Fácil de Usar

• Providencie uma documentação:

  • Escreva docs primeiro;
  • Tenha um README;
  • Providencie um tutorial quick start descrevendo os casos mais comuns;
  • Separe documentação de alto e baixo nível;
  • Use pronomes de gênero neutros;
  • Hospede isso em Read the Docs.

• Escreva testes:

  • Teste com um custom user model;
  • Providencie uma cobertura de código.

• Tenha uma Integração Contínua:

  • Use tox para testar com as mais variadas versões de Python e django
    • Cheque o tox.ini de projetos populares como django-filter e django-taggit;
  • Respeite o PEP 8, use flake8.

• Envie com um projeto de exemplo. Exemplos de implementações:

  • django-guardian;
  • django-haystack;
  • django-avatar.

• Separe abstrações Django em nomes de arquivos comumente usados como views.py, forms.py, fields.py, etc;

• Siga o padrão resource_action em nomes de URLs, como password_reset ou product_detail;

• Nunca confie em modelos de usuário padrão, suporte custom user models:

  • Cheque a implementação de django-registration.

• Providencie uso declarativo. Exemplo de implementações:

  • django-filter filtersets;
  • django-import-export resources.

• Não conecte código implicitamente pelo nome ou módulo. Tenha um registry. Exemplos de implementações:

  • django-contrib-comments moderator registry;
  • django-activity-stream registry.

• Tenha comandos management para necessidades em comum de desenvolvedores. Exemplo de implementações:

  • django-reversion commands;
  • django-haystack commands.

• Use _default_manager, não objects, quando interagir com models do projeto host;

• Seja pythônico:

  • Use generators para lazy evaluation;
  • Use declarações de contexto with para lidar com recursos não gerenciados.

• Previna erros:

  • Providencie checks com Django System check framework.

• Falha rápida:

  • Dispare ImproperlyConfigured se o desenvolvedor cometer erros na configuração.
  • django-filter dispara ImproperlyConfigured quando o desenvolvedor esquece de especificar filterset_class ou model no FilterView;
  • Dispare TypeError ou ValueError quando a aplicação obtém um argumento inválido.

• Internacionalize (I18N) seus strings.

4. Fácil para integrar

• Reduza descontinuidades na integração:
  • Quebrar comportamentos de classes dentro de métodos;
  • Separar comportamento de classes dentro de mixins;
  • Isolar lógica dentro de módulos helper com funções e classes de negócio.
• Use AppConfig:
  • Verifique se seu aplicativo não interrompe quando o AppConfig é estendido.
• Providencie templates padrão:
  • Não coloque diretamente dentro de templates/, mas coloque dentro de templates/app_name/;
  • Garanta que podem ser alterados carregando algum template personalizando com o mesmo caminho.
• Providencie template tags para apresentar dados complexos
• Deixe apenas lógica de apresentação dentro de template tags, quebre o resto da lógica dentro de helpers. Por exemplo:
  • django-avatar tem um avatar template tag para gerar tags img, mas a lógica para gerar URLs avatar é isolado em providers.py;
• Providencie views padrão:
  • Não quebre a configurabilidade dos class-based views. Permita que os atributos e métodos existentes nas views do Django sejam sobrescritos;
  • Quebre lógica de views em comum dentro de mixins.
• Evite models built-in se possível. Caso precise tê-los, providencie um model abstrato e habilite sua aplicação de trabalhar com uma variedade de customizados concretos. Exemplos de implementação:
  • django-taggit custom tag model;
  • django-blog-zinnia custom entry model;
  • django-contrib-comments custom app;
  • Quebre partes comuns de models dentro de models abstratos;
  • Não use model mixins, use models abstratos:
    • Cheque a razão disso em StackOverflow answer.
• Quando usar Generic Foreign Keys, permita que eles sejam substituídos por FKs diretas. Exemplos de implementação:
  • django-guardian support of direct foreign keys;
  • django-taggit support of custom through model.
• Isole lógica de campos form dentro de form fields e widgets:
  • Cheque a implementação em django-recaptcha.
• Isole e lógica de campos model dentro de model fields:
  • Cheque a implementação em django-hashid-field.
• Isole lógica de query dentro de métodos queryset, como filter, update e delete;
• Isole lógica de comportamente a nível de tabela, dentro de métodos manager, como lógica do create;
• Isole lógica de validação dentro de validators;
• Use context processors somente para lógicas globais;
• Use middlewares somente para lógicas globais relacionados ao ciclo request-response ou current user;
• Evite código spathetti nos signals.

5. Manutenção

• Seja transparente sobre bugs, especialmente problemas de segurança;
  • Adicione warnings de segurança no CHANGELOG. Certifique-se de que eles são analisáveis por ferramentas de segurança;
• Não abandone o projeto, give it away.