Lição original: "Git como ferramenta metodológica em projetos de História (parte 1)"

[DanielAlvesLABDH]

O Programming Historian em Português recebeu a seguinte lição original: "Git como ferramenta metodológica em projetos de História (parte 1)", por @ericbrasiln. Agradeço muito ao Eric Brasil o envio desta lição original, iniciando-se agora o processo de revisão e publicação da primeira parte.

A lição está a ser revista nos seus aspectos formais por @anisa-hawes.

Até que um editor seja atribuído, eu servirei como editor temporário.

Peço que os revisores avaliem a necessidade de adequação de dados ou algum conteúdo. Por favor, deixem suas sugestões neste ticket. Para cada modificação a ser sugerida, por favor, peço para indicar as linhas do ficheiro de maneira que facilite os ajustes. O ideal é realizar as modificações após as sugestões dos dois revisores.

Todos os membros da comunidade estão convidados a oferecer feedback construtivo que deve ser publicado neste canal, mas é solicitado que leiam primeiro as diretrizes para revisores (/directrizes-revisor) e sigam a nossa política anti-assédio. Pedimos que todas as revisões parem após o envio da segunda revisão formal para que o autor possa concentrar-se no ajuste da lição. O editor fará um anúncio neste tópico quando isso ocorrer.

Vou me esforçar para manter a conversa aberta aqui no GitHub, mas se alguém sentir a necessidade de discutir algo em particular, pode entrar em contato comigo, ou pode sempre recorrer para o nosso mediador independente se achar necessário.

Se houver alguma preocupação do autor ou dos revisores, eles podem entrar em contato com o mediador do PH em português (Luís Ferla).

[DanielAlvesLABDH]

O @JimmyMedeiros82 aceitou ficar como editor desta proposta de lição original. Ele conduzirá o processo e irá fazer os convites para os dois revisores. Muito obrigado!

[anisa-hawes]

Obrigada, @DanielAlvesLABDH.

Pode encontrar os ficheiros principais aqui:

• .md: /pt/esbocos/originais/git-ferramenta-metodologica-projetos-historia-1
• images: /images/git-ferramenta-metodologica-projetos-historia-1
• assets: [none]

E pode consultar a pré-visualização da lição aqui:

• http://programminghistorian.github.io/ph-submissions/pt/esbocos/originais/git-ferramenta-metodologica-projetos-historia-1

[DanielAlvesLABDH]

Thank you @anisa-hawes. Have a great weekend!

[JimmyMedeiros82]

Olá @felipelmc e @ianaraujo agradeço o aceite de vocês para avaliar a lição original do PHPT!

O foco desta colaboração é avaliar a clareza e o entendimento do texto da nova lição e se há necessidade de adequação de dados ou algum conteúdo. Por favor, deixem suas sugestões neste ticket. Seguimos o padrão das avaliações anteriores, para cada modificação a ser sugerida, por favor, peço para indicar as linhas do ficheiro de maneira que facilite os ajustes. O ideal é realizar as modificações após as sugestões dos dois revisores.

[felipelmc]

Agradeço o convite, @JimmyMedeiros82! Será um prazer colaborar na revisão de mais uma lição. Deixarei minhas sugestões aqui até o fim da semana.

[felipelmc]

Olá, caros! Primeiro, gostaria de parabenizar o @ericbrasiln pela excelente lição. Git e GitHub são ferramentas fundamentais e o esforço de elaborar uma lição acessível e de extrema qualidade como essa é louvável. Trago as minhas sugestões abaixo:

• [x] Linha 58: Acredito que o GitHub Desktop esteja mantido, sim! Inclusive, a última release ocorreu no dia 26-07-23, vejam: https://desktop.github.com/release-notes/.

• [x] Linha 75: Ajustar a frase "O que permite a compreensão geral da história do desenvolvimento de um projeto (Kim et al., 2021, p. 657)." para "Esses mecanismos e informações permitem a compreensão geral da história do desenvolvimento de um projeto (Kim et al., 2021, p. 657)."

• [x] Linha 83: Ajustar "LaTex" para "LaTeX". Seria ideal, inclusive, escrever apenas tex, já que estão sendo listadas extensões de arquivo. Nesse ponto também seria interessante informar que Jupyter Notebooks (ipynb) também fazem parte do grupo de arquivos que o git não consegue identificar quais foram as mudanças específicas.

• [x] Linha 553: Adicionar as aspas iniciais no início da citação

• [x] Linha 557: Adicionar as aspas à citação

• [x] Linha 569: Estou na dúvida se hash é substantivo feminino ou masculino, mas, nas pesquisas que fiz, o correto me parece ser "um hash". Não sei quanto ao Português de Portugal.

Como sugestão final, acredito que vale a pena comentar sobre commits atômicos (https://dev.to/samuelfaure/how-atomic-git-commits-dramatically-increased-my-productivity-and-will-increase-yours-too-4a84), uma boa prática que facilita que a pessoa encontre o commit no qual determinada mudança foi implementada, dentre outras vantagens. Isso me parece mais importante na área de programação, quando uma mudança muito específica pode fazer um código em produção "quebrar", mas certamente é uma boa prática que se estende às Humanidades Digitais.

Fico à disposição no caso de quaisquer questões :)

[JimmyMedeiros82]

Agradeço demais, @felipelmc Contribuição excelente!

[ianaraujo]

Obrigado, @JimmyMedeiros82, pelo convite para revisar a lição. Parabéns @ericbrasiln pela lição escrita. De fato, como pontuou @felipelmc, Git e Github são ferramentas muito úteis e, na minha visão, subutilizadas no ambiente acadêmico. Apresento abaixo algumas sugestões:

• [x] Linha 83: Acredito que é importante deixar claro para o leitor que o Github não foi idealizado e construído para acompanhar mudanças em grandes conjuntos de dados, possivelmente armazenados em arquivos .csv ou .json. Por ser uma ferramenta de versionamento de código (pequenos arquivos de texto), é preciso estar atento ao limite máximo de 100MB por arquivo. Mais informações sobre arquivos grandes podem ser encontradas aqui. Existem outras ferramentas que, ao contrário do Github, se propõem ao versionamento de dados e modelos estatísticos, como https://dvc.org/.

• [x] Linha 84: Na minha visão, acho que seria relevante explicar no corpo do texto (ao invés de usar as notas) como utilizar o .gitignore para ignorar arquivos indesejados no monitoramento do Git, fornecendo exemplos práticos. Muitos pesquisadores podem se deparar com essa necessidade em seu cotidiano, seja para ignorar arquivos muito grandes ou que contêm informações sensíveis, que não devem ser disponibilizadas em um repositório remoto.

• [x] Linha 218: O link para a lição do Programming Historian sobre Bash é para a versão em inglês. Se você conhecer alguma referência sobre Bash em português, sugiro adicionar às notas ou leituras adicionais, visando melhor atender ao público-alvo.

• [x] Linha 355: Ao explicar a importância das mensagens de commit, seria interessante incluir exemplos práticos de boas e más práticas em mensagens de commit. Esse é um assunto crucial, especialmente ao trabalhar de forma colaborativa.

• [x] Linha 571: Em linha com o sugerido por @felipelmc, sugiro a criação de uma seção para abordar a questão dos commits atômicos e boas práticas, principalmente em mensagens de commit, nomeação de branches, etc. Como usuários dessas ferramentas, sem dúvida, teria facilitado meu processo de aprendizagem se eu tivesse conhecido essas abordagens desde o início.

De modo geral, a lição proposta por @ericbrasiln é excelente, muito bem escrita e se mostra pronta para publicação.

Me coloco à disposição para qualquer questão adicional.

[JimmyMedeiros82]

Maravilha, @ianaraujo Agradeço demais pela contribuição com nossa lição.

[JimmyMedeiros82]

@ericbrasiln por favor, poderia efetuar os ajustes necessários? Em seguida, farei a revisão final da lição.

[ericbrasiln]

Muito obrigado @felipelmc e @ianaraujo pela revisão e sugestões.

@JimmyMedeiros82, ao longo da próxima semana farei os ajustes. Abraços

[ericbrasiln]

Olá, colegas.

Fiz as alterções conforme suas sugestões.

Respondo aqui, alguns comentários do @ianaraujo

Linha 83: Acredito que é importante deixar claro para o leitor que o Github não foi idealizado e construído para acompanhar mudanças em grandes conjuntos de dados, possivelmente armazenados em arquivos .csv ou .json. Por ser uma ferramenta de versionamento de código (pequenos arquivos de texto), é preciso estar atento ao limite máximo de 100MB por arquivo. Mais informações sobre arquivos grandes podem ser encontradas aqui. Existem outras ferramentas que, ao contrário do Github, se propõem ao versionamento de dados e modelos estatísticos, como https://dvc.org/.

Concordo com seu comentário, entretanto, como nessa lição não estou abordando diretamente o GitHub (farei isso numa segunda parte da lição), acredito que incluir essa questão pode gerar certa confusão (que já é comum) entre Git e GitHub. Mas reescrevi o trecho sobre arquivos grandes e Git.

Linha 84: Na minha visão, acho que seria relevante explicar no corpo do texto (ao invés de usar as notas) como utilizar o .gitignore para ignorar arquivos indesejados no monitoramento do Git, fornecendo exemplos práticos. Muitos pesquisadores podem se deparar com essa necessidade em seu cotidiano, seja para ignorar arquivos muito grandes ou que contêm informações sensíveis, que não devem ser disponibilizadas em um repositório remoto.

Concordo também, mas assim como na questão anterior, pretendo tratar com calma o .gitignore numa segunda parte da lição. Incluí no corpo do texto uma breve explicação sobre o .gitignore.

Linha 218: O link para a lição do Programming Historian sobre Bash é para a versão em inglês. Se você conhecer alguma referência sobre Bash em português, sugiro adicionar às notas ou leituras adicionais, visando melhor atender ao público-alvo.

A lição já está traduzida e está em fase de revisão para publicação. Acredito que em breve seja publicada, então atualizaremos o link para a versão em português.

Linha 355: Ao explicar a importância das mensagens de commit, seria interessante incluir exemplos práticos de boas e más práticas em mensagens de commit. Esse é um assunto crucial, especialmente ao trabalhar de forma colaborativa.

e

Linha 571: Em linha com o sugerido por @felipelmc, sugiro a criação de uma seção para abordar a questão dos commits atômicos e boas práticas, principalmente em mensagens de commit, nomeação de branches, etc. Como usuários dessas ferramentas, sem dúvida, teria facilitado meu processo de aprendizagem se eu tivesse conhecido essas abordagens desde o início.

Criei um tópico para falar de boas práticas e commits atômicos. Sobre nomeação de branches, será abordado na segunda parte da lição.

Na segunda parte da lição pretendo abordar:

• .gitignore
• Branches
• repositórios remotos
• colaboração no GitHub

Acho que é isso!

Agradeço muito os comentários.

A versão atualizada está aqui: /pt/esbocos/originais/git-ferramenta-metodologica-projetos-historia-1

@JimmyMedeiros82 é comum incluir um agradecimento nas lições ou não? Gostaria de colocar um breve agradecimento, mas não lembro se costumamos fazer isso no PH.

Qualquer outra questão é só falar.

[DanielAlvesLABDH]

Caros, excelente trabalho! Uma lição muito relevante e duas revisões muito atentas. Obrigado ao Jimmy pelo acompanhamento. Quanto aos agradecimentos, acho que se podem colocar numa última frase da lição, por exemplo. Julgo já ter visto assim em lições em inglês. Abraço

[JimmyMedeiros82]

@DanielAlvesLABDH avançamos com mais uma lição! Parabenizo o @ericbrasiln pelo trabalho de desenvolver a lição e agradeço aos colegas @ianaraujo e @felipelmc pelas atentas revisões.

[ericbrasiln]

Maravilha!

Acabo de fazer um commit incluíndo uma frase de agradecimento e fazendo um pequena correção na bibliografia.

Se precisarem de mais alguma coisa é só falar.

[ericbrasiln]

Hi, @anisa-hawes @DanielAlvesLABDH @JimmyMedeiros82

Acredito que eu devo indicar uma imagem para a lição, certo?

Pensei nessa aqui, da British Library. Preciso fazer algum tratamento nela ou isso não é função do autor?

[anisa-hawes]

Thank you, @ericbrasiln. I appreciate you making the selection and I will take care of preparing this lesson avatar 🙂

As this is an original lesson, our next step is copyediting. @joanacvp is going to be the copyeditor of this lesson.

I'd like to ask that no further changes are made to the .md file while Joana is working. She will be in touch with any questions that arise and is aiming to complete this work by ~31st August.

[ericbrasiln]

Bom dia,

Na quinta-feira (24) darei um workshop sobre Git e Github no Labhdufba (presencial, mas também será transmitido no YouTube).

Vou usar a lição como base. Vocês vêem algum problema em citá-la e utilizá-la mesmo que ainda não tenha sido publicada a versão final?

[DanielAlvesLABDH]

Olá @ericbrasiln. Parabéns pela lição, uma vez mais. Gostei muito da imagem. Por mim não vejo problema em que a lição seja citada. Estamos quase a terminar o processo de publicação. Abraço

[anisa-hawes]

Hello @DanielAlvesLABDH ,

This lesson is almost ready for your final review ahead of transfer to Jekyll.

Preview: http://programminghistorian.github.io/ph-submissions/pt/esbocos/originais/git-ferramenta-metodologica-projetos-historia-1

Publisher's sustainability + accessibility actions:

• [x] Copyediting (thank you, @joanacvp)
• [x] Typesetting
• [x] Addition of Perma.cc links
• [x] Addition of alt-text for all figures
• [x] Check/resize images
• [x] Check/adjust image filenames
• [x] Receipt of author's copyright agreement (Hello @ericbrasiln. I've emailed you with this request!)
• [x] Add doi

Editorial input to YAML:

• [x] Selection of lesson avatar for /gallery
• [x] Addition of avatar_alt: (Hello @ericbrasiln. I've prepared + uploaded the image you selected /gallery/git-ferramenta-metodologica-projetos-historia-1.png. Could you provide alt-text for the YAML field avatar_alt: to describe this image?)
• [x] Addition of abstract:
• [x] Addition of difficulty:
• [x] Addition of topics:
• [x] Creation of author(s) bio for ph_authors.yml

Files to be transferred to Jekyll:

• .md file: /esbocos/originais/git-ferramenta-metodologica-projetos-historia-1.md
• images: /images/git-ferramenta-metodologica-projetos-historia-1
• assets: /assets/git-ferramenta-metodologica-projetos-historia-1
• gallery avatar: /gallery/git-ferramenta-metodologica-projetos-historia-1
• original avatar: /gallery/originals/git-ferramenta-metodologica-projetos-historia-1

Promotion:

• [ ] Prepare announcement post (using template)
• [ ] Prepare x2 future posts for our Twitter/Mastodon Bot

[anisa-hawes]

Olá @ericbrasiln,

I notice that you use the Author and Date system of citation rather than Notes and Bibliography in the following places:

line 47, 85, 351, 598, 753 : Ram et al., 2013 line 55 : Guerrero-Higueras et al., 2020 line 63, 69, 77 : Chacon e Straub, 2014 line 75 : Bryan, 2018 line 75 : Kim et al., 2021 line 557 : Gibbs e Owens, 2013

Do you have time to adjust these so that they are endnotes instead? I don't find all of these in the Leituras adicionais section either, so it isn't possible for a reader to know which works are referenced.

Let me know if I can help. I'm happy to renumber and double-check the endnotes after you've made the additions.

Thank you.

[ericbrasiln]

hi @anisa-hawes ! Thank you very much for the work on the lesson!

I will send the form later today.

Can I list here all the missing references (I just need to find them in my Zotero, so it will be easy)?

[ericbrasiln]

@anisa-hawes here is the alt-text for the avatar.

avatar_alt: "máquina circular para impressão gráfica com oito saídas"

[anisa-hawes]

Thank you, @ericbrasiln!

• [x] Copyright declaration recieved
• [x] avatar_alt: added

[ericbrasiln]

@anisa-hawes Here is the updated list of references:

Baker, James. “Preservar os seus dados de investigação”. Traduzido por Márcia T. Cavalcanti. The Programming Historian em português, nº 1 (29 de janeiro de 2021). https://doi.org/10.46430/phpt0001.

Bird, Christian, Peter C. Rigby, Earl T. Barr, David J. Hamilton, Daniel M. German, e Prem Devanbu. “The promises and perils of mining git”. Em 2009 6th IEEE International Working Conference on Mining Software Repositories, 1–10, 2009. https://doi.org/10.1109/MSR.2009.5069475.

Brasil, Eric. “Criação, manutenção e divulgação de projetos de História em meios digitais: git, GitHub e o Programming Historian”. Apresentação. Zenodo, 2022. https://doi.org/10.5281/zenodo.6566754.

Bryan, Jennifer. “Excuse Me, Do You Have a Moment to Talk About Version Control?” The American Statistician 72, nº 1 (2 de janeiro de 2018): 20–27. https://doi.org/10.1080/00031305.2017.1399928.

Chacon, Scott, e Ben Straub. Pro Git. 2º edição. New York: Apress, 2014.

Gibbs, Fred, e Trevor Owens. “The Hermeneutics of Data and Historical Writing”. Em Writing History in the Digital Age, 159–70. Ann Arbor, MI: University of Michigan Press, 2013.

Guerrero-Higueras, Ángel Manuel, Camino Fernández Llamas, Lidia Sánchez González, Alexis Gutierrez Fernández, Gonzalo Esteban Costales, e Miguel Ángel Conde González. “Academic Success Assessment through Version Control Systems”. Applied Sciences 10, nº 4 (janeiro de 2020): 1492. https://doi.org/10.3390/app10041492.

Kim, Youngtaek, Jaeyoung Kim, Hyeon Jeon, Young-Ho Kim, Hyunjoo Song, Bohyoung Kim, e Jinwook Seo. “Githru: Visual Analytics for Understanding Software Development History Through Git Metadata Analysis”. IEEE Transactions on Visualization and Computer Graphics 27, nº 2 (fevereiro de 2021): 656–66. https://doi.org/10.1109/TVCG.2020.3030414.

Loeliger, Jon, e Matthew McCullough. Version Control with Git: Powerful tools and techniques for collaborative software development. 2º edição. Sebastopol, CA: O’Reilly Media, 2012.

Faure, Samuel-Zacharie. “How Atomic Git Commits Dramatically Increased My Productivity - and Will Increase Yours Too”. DEV Community, 7 de março de 2023. https://dev.to/samuelfaure/how-atomic-git-commits-dramatically-increased-my-productivity-and-will-increase-yours-too-4a84. Acesso em: 9 ago. 2023.

[ericbrasiln]

Hi, @anisa-hawes

I adjusted the references to endnotes and only kept references that had not been cited throughout the lesson in the 'Leituras adicionais' section.

Check the changes here.

If any other changes are necessary, just let me know.

[anisa-hawes]

Many thanks, @ericbrasiln.

I've reviewed the changes you've made, and have followed up with a few very small adjustments and corrections https://github.com/programminghistorian/ph-submissions/commit/d4b5eec6a923993ab08196638da8a07f6c8a2c12

One thing I notice is that the endnote [^7] is still included at line 781, but this isn't referenced in the lesson. Did you intend to remove this note, or would you like to keep it in? (If we keep it in, I think it would be good to use the system you've used throughout your endnotes, where you use a reference word instead of a number).

[ericbrasiln]

Hi, @anisa-hawes I forgot to change this endnote! But I just fixed it in this commit: https://github.com/programminghistorian/ph-submissions/commit/fba831afc19780733bf1ad147dda81e467306b85 Thanks

[anisa-hawes]

Olá @DanielAlvesLABDH ,

This lesson is ready!

Preview: http://programminghistorian.github.io/ph-submissions/pt/esbocos/originais/git-ferramenta-metodologica-projetos-historia-1

Publisher's sustainability + accessibility actions:

• [x] Copyediting (thank you, @joanacvp)
• [x] Typesetting
• [x] Addition of Perma.cc links
• [x] Addition of alt-text for all figures
• [x] Check/resize images
• [x] Check/adjust image filenames
• [x] Receipt of author's copyright agreement (thank you, @ericbrasiln)
• [x] Add doi

Editorial input to YAML:

• [x] Selection of lesson avatar for /gallery
• [x] Addition of avatar_alt:
• [x] Addition of abstract:
• [x] Addition of difficulty:
• [x] Addition of topics:
• [x] Creation of author(s) bio for ph_authors.yml

Files to be transferred to Jekyll:

• .md file: /esbocos/originais/git-ferramenta-metodologica-projetos-historia-1.md
• images: /images/git-ferramenta-metodologica-projetos-historia-1
• assets: /assets/git-ferramenta-metodologica-projetos-historia-1
• gallery avatar: /gallery/git-ferramenta-metodologica-projetos-historia-1
• original avatar: /gallery/originals/git-ferramenta-metodologica-projetos-historia-1

Promotion:

• [x] Prepare announcement post (using template)
• [ ] Prepare x2 future posts for our Twitter/Mastodon Bot

[DanielAlvesLABDH]

Fiz uma revisão final com ligeiros ajustes e vou passar à publicação. Vamos ter a nossa segunda lição original e agradeço muito ao Eric (@ericbrasiln) pelo trabalho desenvolvido. Parabéns! Agradecer ainda ao Jimmy (@JimmyMedeiros82), pelo trabalho editorial, e ao Ian (@ianaraujo) e Felipe (@felipelmc) pelas revisões. Também à Anisa (@anisa-hawes) e à Joana (@joanacvp).

[ericbrasiln]

Que maravilha!

Também agradeço pelo trabalho de todos e todas nesse processo de revisão e publicação.

Em breve, submeto a parte 2! 😀

[DanielAlvesLABDH]

Publicada! Obrigado a todos! @anisa-hawes, I think I have to do a couple of posts for Twitter for several lessons (including the ones about this lesson). Could you help me pointing what is missing and I will take a look at all during the week? Thanks