Skip to content

Latest commit

 

History

History
262 lines (174 loc) · 15.5 KB

CONTRIBUTING-pt_BR.md

File metadata and controls

262 lines (174 loc) · 15.5 KB
Raw

Leia em outros idiomas

Acordo de Licença do Contribuidor

Ao contribuir você concorda com a LICENÇA deste repositório.

Código de Conduta do Contribuidor

Ao contribuir você concorda em respeitar o Código de Conduta deste repositório. (traduções)

Em poucas palavras

  1. "Um link para baixar um livro facilmente" nem sempre é um link para um livro gratuito. Por favor contribua apenas com conteúdo gratuito. Certifique-se de que é grátis. Não são aceitos links para páginas que requerem um endereço de email para obter livros, mas aceitamos listas que requerem.

  2. Não é necessário saber Git: se você encontrou algo interessante que não está presente neste repositório, por favor abra uma Issue com todas as propostas de links.

    • Se você sabe Git, faça um Fork do repositório e mande um Pull Request (PR).

  3. Possuimos 6 tipos de listas. Escolha a mais adequada:

    • Livros: PDF, HTML, ePub, sites baseados no gitbook.io, um repositório Git, etc.
    • Cursos: Um curso é um material didático que não é um livro. Isso é um curso.
    • Tutoriais Interativos: Um site interativo que permite ao usuário digitar código ou comandos e computa o resulta (por "computar" não queremos dizer "avaliar"). Por exemplo: Try Haskell, Try GitHub.
    • Playgrounds : são websites interativos, jogos ou aplicativos para aprender programação. Escreve, compila (ou roda), e compartilha techos de código. Playgrounds quase sempre permitem que se realize um fork no código e coloque a mão na massa.
    • Podcasts e Screencasts : Podcasts e Vídeocasts.
    • Conjuntos de Problemas e Programação Competitiva : Um site ou software que permite avaliar suas habilidades de programação através da resolução de problemas simples ou complexos, com ou sem revisão de código, com ou sem comparação de resultados com outros usuários.

  4. Certifique-se de seguir as diretrizes abaixo e respeitar a formatação de Markdown dos arquivos.

  5. GitHub Actions executará testes para assegurar que suas listas estão em ordem alfabética e seguem as regras de formatação. Cerfique-se de que suas alterações passaram pelos testes.

Diretrizes

  • certifique-se de que o livro é gratuito. Verifique múltiplas vezes se necessário. Comentar no PR por quê você acha que o livro é gratuito ajuda os administradores.
  • não aceitamos arquivos hospedados no Google Drive, Dropbox, Mega, Scribd, Issuu e outras plataformas similares de upload de arquivos.
  • insira seus links em ordem alfabética, como descrito abaixo.
  • use o link com a fonte mais oficial (isso significa que o site do próprio autor é melhor que o site da editora, que é melhor que sites de terceiros)
    • sem serviços de hospedagem de arquivos (isso inclui, mas não se limita a, links do Dropbox e Google Drive)
  • sempre prefira um link https em vez de http -- desde que estejam no mesmo domínio e sirvam o mesmo conteúdo.
  • em domínios raiz, remova a barra final: http://exemplo.com ao invés de http://exemplo.com/
  • sempre prefira o link mais curto: http://exemplo.com/dir/ é melhor que http://exemplo.com/dir/index.html
    • sem links vindos de encurtadores de links
  • prefira o link "current" ao invés de "version": http://exemplo.com/dir/book/current/ é melhor que http://exemplo.com/dir/book/v1.0.0/index.html
  • se um link possui um certificado expirado/autoassinado/problema de SSL de qualquer outro tipo:
    1. substitua-o por seu equivalente http se possível (pois aceitar exceções pode ser complicado em dispositivos móveis).
    2. mantenha-o se não houver versão http disponível, mas o link continua acessível através de https adicionando uma exceção ao browser ou ignorando o aviso.
    3. remova-o caso contrário.
  • se o link existir em múltiplos formatos, adicione um link separado com uma observação sobre cada formato.
  • se o material existe em diferentes lugares na Internet
    • use o link com a fonte mais oficial (isso significa que o site do autor é melhor que o site da editora que é melhor que sites de terceiros)
    • se eles referenciam diferentes edições, e você julgar que essas edições são diferentes o bastante para mantê-las, adicione um link separado com uma observação para cada edição (veja Issue #2353 para contribuir com a discussão sobre formatação).
  • prefira commits atômicos (um commit para cada adição/deleção/modificação) ao invés de commits maiores. Não é necessário fazer o squash de seus commits antes de submeter um PR. Nunca iremos impor esta regra dado que é apenas uma questão de conveniência para os mantenedores).
  • se o livro for mais antigo, inclua a data de publicação no título.
  • inclua o(s) nome(s) do(s) autor(es) onde for apropriado. Você pode encurtar a lista de autores com "et al".
  • se o livro não estiver completo, e ainda está sendo escrito, adicione a notação "in process", como descrito abaixo.
  • Se um recurso for restaurado utilizando a Internet Archive's Wayback Machine (ou similar), adicione a notação "archived", como descrito abaixo. As melhores versões para uso são recentes e completas.
  • se um endereço de email ou configuração de conta for solicitado antes que o download seja habilitado, adicione uma observação no idioma apropriado e entre parênteses. Por exemplo: (endereço de email é *pedido*, não obrigatório).

Formatação

  • Todas as listas são arquivos .md. Tente aprender a sintaxe de Markdown. É simples!
  • Todas as listas começam com um Índice. A ideia é listar e "linkar" todas as seções e subseções lá. Mantenha-o em ordem alfabética.
  • Seções são títulos de nível 3 (###), e subseções são títulos de nível 4 (####).

A ideia é ter:

  • 2 linhas em branco entre o último link e a nova seção.
  • 1 linha em branco entre o título e o primeiro link da seção.
  • 0 linhas em branco entre dois links.
  • 1 linha em branco ao final de cada arquivo .md.

Exemplo:

[...]
* [Um Livro Incrível](http://exemplo.com/exemplo.html)
                                (linha em branco)
                                (linha em branco)
### Exemplo
                                (linha em branco)
* [Outro Livro Incrível](http://exemplo.com/livro.html)
* [Outro Livro Qualquer](http://exemplo.com/outro.html)

  • Não coloque espaços entre ] e (:

    RUIM: * [Outro Livro Incrível] (http://exemplo.com/livro.html)
BOM : * [Outro Livro Incrível](http://exemplo.com/livro.html)

  • Se incluir o autor, use - (um traço envolto por espaços simples):

    RUIM: * [Outro Livro Incrível](http://exemplo.com/livro.html)- Fulano de Tal
BOM : * [Outro Livro Incrível](http://exemplo.com/livro.html) - Fulano de Tal

  • Coloque um espaço simples entre o link e seu formato:

    RUIM: * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf)(PDF)
BOM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf) (PDF)

  • Autor vem antes do formato:

    RUIM: * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf)- (PDF) Fulana de Tal
BOM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf) - Fulana de Tal (PDF)

  • Múltiplos formatos:

    RUIM: * [Outro Livro Incrível](http://exemplo.com/)- Fulano de Tal (HTML)
RUIM: * [Outro Livro Incrível](https://downloads.exemplo.org/livro.html)- Fulano de Tal (download site)
BOM : * [Outro Livro Incrível](http://exemplo.com/) - Fulano de Tal (HTML) [(PDF, EPUB)](https://downloads.exemplo.org/livro.html)

  • Inclua o ano de publicação no título de livros antigos:

    RUIM: * [Um Livro Muito Incrível](https://exemplo.org/livro.html) - Fulana de Tal - 1970
BOM : * [Um Livro Muito Incrível (1970)](https://exemplo.org/livro.html) - Fulana de Tal

  • Livros em processo:

    BOM  : * [Será Um Livro Incrível Em Breve](http://exemplo.com/livro2.html) - Fulano de Tal (HTML) (:construction: *em processo*)

  • Archived link:

    BOM  : * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)*

Alphabetical order

  • Quando há múltiplos títulos começando com a mesma letra, ordene-os pela segunda letra e assim por diante. Por exemplo: aa vem antes de ab.
  • um dois vem antes de umdois

Se observar um link no lugar errado, verifique a mensagem de erro no linter para saber quais linhas devem ser trocadas.

Observações

As noções básicas são relativamente simples, mas há uma grande diversidade de materiais que listamos. Aqui estão algumas observações sobre como tratamos essa diversidade.

Metadados

Nossas listas fornecem um conjunto mínimo de metadados: títulos, URLs, criadores, plataformas e notas de acesso.

Títulos
  • Sem títulos inventados. Tentamos utilizar os títulos dos próprios materiais; contribuidores são aconselhados a não inventar títulos ou usá-los editorialmente se possível evitar. Uma exceção é para trabalhos antigos; se forem primariamente de interesse histórico, o ano entre parênteses adicionado ao título ajuda os usuários a saber se é de seu interesse.
  • Sem título EM CAIXA ALTA. Normalmente "title case" é apropriado. Em caso de dúvida, use a capitalização da fonte.
  • Nada de emojis.
URLs
  • Não permitimos encurtadores de URLs.
  • Códigos de rastreamento devem ser removidos da URL.
  • URLs internacionais devem ser escapadas. Barras de endereço dos navegadores normalmente renderizam eles em Unicode, mas use copiar e colar, por favor.
  • URLs seguras (https) sempre são preferidas no lugar de URLs não-seguras (http) quando a HTTPS estiver disponível.
  • Não gostamos de URLs que apontam para páginas que não hospedam o material listado, mas apontam para outro lugar.
Criadores

  • Queremos creditar os criadores do material gratuito apropriadamente, incluindo tradutores!

  • Para trabalhos traduzidos, o autor original deve ser creditado. Recomendamos utilizar MARC relators para creditar criadores tanto quanto autores, como no exemplo:

    * [Um Livro Traduzido](http://example.com/book-pt_BR.html) - Fulano de Tal, `trl.:` Beltrano O Tradutor

    aqui a marcação trl.: utiliza o código MARC ralator para "tradutor".

  • Use vírgula , para delimitar cada ítem na lista de autores.

  • Você pode encurtar a lista de autores com "et al.".

  • Não permitimos links para Criadores.

  • Para compilações ou trabalhos remixados, o "criador" pode precisar de uma descrição. Por exemplo, os livros "GoalKicker" ou "RIP Tutorial" são creditados como "Compilado da documento do StackOverflow" (em inglês: "Compiled from StackOverflow documentation").

Plataforma e Notas de Acesso
  • Cursos. Especificamente para nossa lista de cursos, a plataforma é uma parte importante da descrição do material. Isso acontece pois plataformas de cursos possuem affordances e modelos de acesso diferentes. Normalmente não listamos um livro que requer um cadastro, muitas plataformas de cursos possuem affordances que não funcionam sem algum tipo de conta. Exemplos de plataformas de cursos incluem Coursera, EdX, Udacity, e Udemy. Quando o curso depende da plataforma, o nome da plataforma deve ser listado em parênteses.
  • YouTube. Temos muitos cursos que consistem em playlists do YouTube. Não listamos YouTube como uma plataforma, tentamos listar o criador no YouTube, que normalmente é uma subplataforma.
  • Vídeos do YouTube. Normalmente não usamos vídeos do YouTube individuais a não ser que tenham mais de uma hora e sejam estruturados como um curso ou tutorial.
  • Leanpub. Leanpub hospeda livros com uma variedade de modelos de acesso. Algumas vezes, um livro pode ser lido sem necessidade de registro; algumas vezes um livro requer uma conta Leanpub para acesso gratuito. Dada a qualidade dos livros e a mistura e fluidez dos modelos de acesso do Leanpub, permitimos a listagem deste com uma observação de acesso *(Conta Leanpub ou email válido solicitado)*.

Gêneros

A primeira regra ao decidir a qual lista um material pertence é ver como o próprio material se descreve. Se diz que é um livro, então talvez seja um livro.

Gêneros não listados

Dada a vastidão da Internet, não incluimos em nossas listas:

  • blogs
  • posts de blog
  • artigos
  • sites (exceto aquela que hospedam MUITOS dos ítens que listamos).
  • vídeos que não são cursos ou screencasts.
  • capítulos de livros.
  • amostras de livros
  • IRC ou canais do Telegram
  • Slacks ou listas de email

Nossas listas de programação competitiva não são tão estritas quanto a essas exclusões. O escopo do repositório é determinado pela comunidade; se deseja sugerir uma mudança ou adição ao escopo, por favor use uma issue para fazer a sugestão.

Livros vs. Outras Coisas

Não somos tão exigentes quanto a definição de "livro". Aqui estão alguns atributos que significam que um material é um livro:

  • possui um ISBN (International Standard Book Number)
  • possui um sumário
  • uma versão baixável é oferecida, especialmente arquivos ePub
  • possui edições
  • não depende de conteúdo interativo ou vídeos
  • tenta cobrir um tópico de forma abrangente
  • é autocontido

Há diversos livros que listamos que não possuem esses atributos; pode depender do contexto.

Livros vs. Cursos

Algumas vezes pode ser difícil de distinguir!

Cursos normalmente possuem manuais associados, que listaríamos em nossas listas de livros. Cursos possuem aulas, exercícios, provas, anotações ou outros materiais didáticos. Uma única aula ou vídeo por si só não é um curso. Um Powerpoint não é um curso.

Tutoriais Interativos vs. Outras coisas

Se você pode capturar a tela ou imprimí-la e reter sua essência, então não é um Tutorial Interativo.

Automação

  • Aplicação das regras de formatação é automatizada via GitHub Actions usando fpb-lint (veja .github/workflows/fpb-lint.yml)

  • Validação de URL usa awesome_bot

  • Para ativar a validação de URL, dê push num commit que inclua uma mensagem de commit contendo check_urls=file_to_check:

    check_urls=free-programming-books.md free-programming-books-pt_BR.md

  • Você pode especificar mais de um arquivo para checagem, usando um espaço simples para separar cada entrada.

  • Se você especificar mais de um arquivo, os resultados de build serão baseados no resultado do último arquivo verificado. Você deve se atentar para o fato de que pode obter um build com verde de sucesso devido a isso. Então, certifique-se de inspecionar o build log ao final de cada Pull Request clicando em "Show all checks" -> "Details".