source("config/_setup.R") opts_chunk$set(eval = FALSE)
Esse documento descreve o roteiro de trabalho no labestData, desde a instalação do software até os passos para inclusão das contribuições. Os primeiros 4 itens precisam ser feitos apenas uma vez por máquina, as milestones e issues são feitos uma vez por obra, enquanto que os demais procedimentos tem uma peridiodicidade semanal.
O Git é um sistema de controle de versão. Para instalar o Git no Linux, execute no terminal as instruções abaixo.
# Instalar no Linux (Ubuntu e Mint). sudo apt-get install git git-core git-man git-gui git-doc \ ssh openssh-server openssh-client gitk meld -y
Para instalar no Windows, baixe o *.exe
disponível no endereço
https://git-scm.com/download/win.
Após instalar, é necessário configurar sua conta com as suas informações pessoais: nome e e-mail. Execute no terminal do Linux (se Linux) ou no Git-bash (se Windows), as intruções abaixo substituindo os campos entre aspas pelas suas informações.
# Configura informações pessoais. git config --global user.name "Seu Nome Aqui" git config --global user.email "seuemail@aqui.com" # Mostra as configurações feitas. git config --list
Essas instruções escrevem um arquivo oculto na home do usuário chamado
.gitconfig
. Você pode abrir e editar esse arquivo se quiser, inclusive
para incluir atalhos (aliases) de comandos, mas tenha cuidado para não
comprometê-lo com erros. Veja um exemplo de arquivo
.gitconfig
.
Depois de instalar o Git é necessário estabelecer comunição com o servidor do serviço GitLab para que um conteúdo (arquivos) seja transferido entre cliente (computador do usuário) e servidor (computador que hospeda o GitLab). A autenticação entre as máquinas é baseada em chaves. Para gerar um par de chaves, execute as instruções abaixo no terminal ou git-bash, substituindo o e-mail pelo seu. O prompt vai pedir para que você forneça uma passphrase mas você pode apenas pressionar ENTER.
ssh-keygen -t rsa -C "seuemail@aqui.com"
No output do terminal será informado o endereço do par de arquivos
gerados: id_rsa
e id_rsa.pub
. Esse par é único. Abra o arquivo
id_rsa.pub
em um editor de texto e copie o seu conteúdo sem
modificá-lo. Entre em https://gitlab.c3sl.ufpr.br/profile/keys, cole o
conteúdo no campo key e dê um título no campo title. Recomenda-se
que o título informe o computador que contem as chaves (e.g. PC-casa,
notebook, PC-PET). Clique em Add key para concluir.
Para finalizar, teste se a autenticação está sendo feita. Execute no terminal ou git-bash a instrução abaixo.
# Testa a comunição entre cliente (você) e servidor (GitLab).
ssh -T git@gitlab.c3sl.ufpr.br
Se for retornado um Welcome, então o procedimento foi realizado com sucesso. Importante: sempre que você executar o comando que gera as chaves, novas chaves serão geradas e você terá que substituir as chaves cadastradas anteriormente (a menos que você gere em outro diretório ou faça backup).
devtools
e roxygen2
O desenvolvimento do pacote labestData é baseado no uso do pacote
devtools
com a documentação escrita no formato roxygen2
.
Para instalar esses pacotes, execute em uma sessão R os códigos abaixo.
install.packages(c("devtools", "roxygen2"), dependencies = TRUE)
O devtools
tem dependências do sistema operacional. Se a sua
instalação no Linux não der certo, leia o output no console que,
normamente, é indicado lá o que não foi encontrado. Em geral, basta
instalar as "libs" abaixo.
sudo apt-get install libcurl4-openssl-dev libssl-dev
Depois de instalar, tente carregar os dois pacotes.
library(devtools) library(roxygen2)
Para trabalhar no labestData você precisa ter uma cópia do
repositório. Abre o terminal ou git-bash em um diretório para fazer uma
cópia do labestData dentro dele. O comando cd
(change directory)
muda de diretórios. Além disso, você pode clicar com o botão direito do
mouse no espaço em branco do navegador de arquivos (Nautilus ou Windows
Explorer) e clicar em Open in Terminal ou Open gih-bash here para
abri-los no diretório exibido pelo navegador de arquivos.
Para clonar o repositório, execute a instrução abaixo.
# Clona o repositório do labestData.
git clone git@gitlab.c3sl.ufpr.br:pet-estatistica/labestData.git
Agora com a cópia, você pode explorar o projeto e fazer contribuições ao mesmo. Os comandos Git abaixo vão fazer um tour pelo labestData.
# Mostra o diretório atual. pwd # Move para o diretório recém clonado do labestData. cd labestData/ # Mostra o estado do repositório. git status # Exibe todos os ramos presentes. Com asterisco é o ramo atual. # Sem argumentos equivale a -l (local), -r (remotes), -a (all). git branch git branch -l git branch -r git branch -a # Mostra o log (histórico) do projeto. Pressione q para sair. git log git log --oneline # Abre a aplicação gitk para navegar no projeto. gitk
Toda obra no labestData é uma milestone. A tradução literal é pedra de milha. A milestone na realidade é a definição de uma meta. Uma milestone é um coletivo de issues. Issue é um assunto ou tópico. No projeto labestData, issue é a definição do trabalho de uma semana. Portanto, uma milestone é uma obra, e os issues dessa milestone são fragmentos dessa obra que serão trabalhados em uma semana.
Para criar uma milestone, acesse https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/milestones e clique em New Milestone. Preencha o campo descrição com detalhes da obra, como título, autores, ano, editora. Visite as milestones já criadas para ver exemplos.
Dentro da milestone recém criada, clique em New Issue
para criar os
issues. Na descrição dos issues indique com detalhes o trabalho a
ser feito naquele issue. Por exemplo, indique a tabela/página dos
conjuntos de dados a serem incluídos com esse issue. Ao criar o
issue escolha uma label condizente com o tema da obra.
Cada issue deve ter conteúdo programado para uma semana de desenvolvimento. Pela experiência adquirida, isso equivale à 2 tabelas grandes (maior que meia página) ou 5 tabelas médias (até 10 linhas) ou 8 tabelas pequenas (como tabelas de contigência). Lembre-se, o custo maior de tempo está muitas vezes na documentação do conjunto de dados do que na digitação dos mesmos.
O ideal é que toda a obra seja fragmentada em issues dentro da milestone no início do período de desenvolvimento do projeto. Isso é fundamental para o planejamento individual e coletivo dos desenvolvedores do projeto.
Você pode nagegar pelos issues do projeto em https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/issues. É possível aplicar filtros para o autor, milestone ou label. Perceba que todas as issues tem um número único. Esse número será usado como parte do nome dos branches de desenvolvimento.
Agora que a obra já possui milestone e issues com seus respectividos números, vamos criar ramos para inclusão das contribuições previstas no issue.
O branch de desenvolvimento é autor numerado, ou seja, composto pelo
nome do autor e número do issue (e.g. walmes159
). Esse ramo é sempre
extraído do branch baby
, que tem apenas o conteúdo mínimo
necessário. Antes, no entanto, é recomendado incorporar possíveis
atualizações no baby
. Os comandos abaixo ilustram isso.
# Muda para o ramo baby. git checkout baby # Atualiza para incorporar possíveis atualizações feitas. git pull origin baby # Cria um ramo a partir do baby. git checkout -b seunome123 # Mostra o ramo atual. Deve estar com asterisco o seunome123. git branch
O ciclo de vida dos ramos de desenvolvimento (ou demanda) é de uma
semana. Ao final de cada semana eles são incorporados ao ramo devel
e
depois são removidos. Só existem três ramos permanentes: baby
, devel
e master
.
Essa parte consiste basicamente em criar 4 arquivos para cada conjunto
de dados: data-raw/*.txt
, data/*.rda
, R/*.R
e
man/*.Rd
. Considerando que o nome do conjunto de dados seja dados
,
por simplicidade, teríamos então a seguinte estrutura.
labestData/ |-- DESCRIPTION |-- NAMESPACE |-- data-raw/ | `-- dados.txt 1. Digitar os dados e criar arquivo txt. |-- data/ | `-- dados.rda 2. Gerar rda com use_data(dados). |-- R/ | `-- dados.R 3. Gerar esqueleto com roxy_data(dados) `-- man/ e preencher. `-- dados.Rd 4. Gerar documentação com document().
Algumas funções foram criadas para auxiliar no desenvolvimento do
labestData, como a roxy_data()
. Elas estão disponíveis no snippet
46 do GitLab: https://gitlab.c3sl.ufpr.br/snippets/46. Recomenda-se
que você tenha um script com os códigos para trabalhar no labestData
e que carrege as funções no snippet ao iniciar sua sessão R. O
repositório não versiona arquivos com nome roteiro.R, portanto
considere nomear seu script dessa forma.
# Abre no navegador o snippet 46. browseURL("https://gitlab.c3sl.ufpr.br/snippets/46/") # Carrega as funções do definidas no snippet 46. source("https://gitlab.c3sl.ufpr.br/snippets/46/raw")
txt
Existem várias maneiras de gerar o arquivo *.txt
e destacamos três:
digitar na planilha e exportar pela planilha, digitar na planilha e
exportar pelo R, digitar no R e exportar pelo R.
Digitar na planilha e exportar pela planilha
: Consiste em digitar os dados em uma planilha eletrônica, copiar a
região com os dados, criar um arquivo txt
vazio em data-raw/
e
colar o conteúdo copiado da planilha dentro. As colunas serão
separadas por tabulação.
Digitar na planilha e exportar com o R
: Digitar os dados na planilha eletrônica, copiar a região com os dados,
carregar pelo R com read.table("clipboard", header = TRUE, sep =
"\t")
. Depois escrever em data-raw/
com a função write2txt(dados)
(disponível no snippet 46).
Digitar no R e exportar com o R
: Digitar os dados com o R usando scan()
ou edit()
e exportar com a
função write2txt(dados)
. Essa opção é bastante vantajosa quando você
tem dados com estrutura regular, como os de experimentos
planejados. Você pode criar as estruturas com expand.grid()
e então
só digitar a variável resposta.
rda
O arquivo rda
pode ser gerado com a função use_data()
do pacote
devtools
.
# Gera o arquivo dados.rda no diretório data/. use_data(dados)
Depois de criar o arquivo rda
, você deve remover esse objeto do da
memória e carregar o labestData com load_all()
. Esse é momento de
experimentar o conjunto de dados para ver se ele não contém erros.
# Remove o objeto "dados" da memória. rm("dados") # Carrega os objetos do labestData. Isso vai carregar o dados. load_all() # Objetos do labestData. ls("package:labestData") # Mostra a estrutura do objeto. str(dados)
R
O arquivo R vai conter a documentação do conjunto de dados escrito no
formato definido pelo pacote
roxygen2
. Esse
formato será transcrito para o formato oficial de documentação R, cuja
extensão de arquivo é Rd
(R documentation), e se assemelha aos
textos LaTeX.
Para gerar o arquivo R com uma documentação prévia, execute a função
roxy_data()
definida no snippet.
# Cria o arquivo dados.R no diretório R/. roxy_data(dados)
A função roxy_data()
criará o arquivo R
com parte da documentação
preenchida. Abra o arquivo e complete com as informações restantes.
Rd
O arquivo Rd
é gerado automaticamente, a partir do arquivo R, pela
função document()
do devtools. A função check_man()
verifica se
existe problemas com a documentação gerada, como campos mal formados,
inexistentes ou falta de chaves em algum ambiente.
# Gera a documentação dados.Rd em man/. document() # Verifica se a documentação não contém erros. check_man()
# Carrega as funções do definidas no snippet 46. source("https://gitlab.c3sl.ufpr.br/snippets/46/raw") # Carregar os dados no txt (opção 1). dados <- read.table("data-raw/dados.txt", header = TRUE, sep = "\t") # Carregar os dados da área de transferência (opção 2). dados <- read.table("clipboard", header = TRUE, sep = "\t") # IMPORTANT: Use esses dados para ver se estão corretos. library(devtools) # Cria o txt no diretório data-raw/. write2txt(dados) # Criar o rda no diretório data/. use_data(dados) # Remover ele do workspace. rm("dados") # Carregar o labestData em desenvolvimento. load_all() # Exibe o nome dos objetos do pacote. ls("package:labestData") # Mostra estrutura dos dodos. str(dados) # Cria o arquivo com a documentação parcialmente preenchido. roxy_data(dados) # Abrir o arquivo R gerado no diretório R/ e editar. # Gera o arquivo Rd no diretório man/. document() # Busca por erros na documentação gerada. check_man() # Mostra o diretório em forma de árvore. dirtree("../")
Depois de adicionados os 4 arquivos referentes ao conjunto de dados, é necessário fazer uma verificação integral do pacote. Caso erros tenham sido introduzidos, nessa fase serão indenficados para serem corrigidos antes de serem enviados para o repositório remoto. Procure sempre subir para o repositório remoto contribuições estáveis.
# Verificação integral. Gera manual mas não as vinhetas. Resultados # ficam em diretório ao lado do atual. check(manual = TRUE, vignettes = FALSE, check_dir = "../") # Cria o arquivo comprimido (zip, tar.gz) para distribuição do pacote. build(manual = TRUE, vignettes = TRUE)
O recurso mais utilizado por desenvolvedores do labestData e que é permanente no projeto é o commit. Por isso, é importante fazer o commit de forma correta para tirarmos ainda mais vantagem desse incrível recurso. Algumas diretrizes para fazer commits são dadas na página oficial do Git. Destacaremos as mais relevantes para o labestData.
Faça commits de mudanças completas : Apenas faça commits de arquivos para unidades completas de algo. Por exemplo, não faça commit de um texto com frases incompletas, não faça commit de uma função cujo código não foi terminado de escrever.
Faça commits pensando que vai precisar revertê-los : Antes de fazer um commit, imagine que vai precisar revertê-lo, voltar para o instante antes de fazê-lo. Existe um jeito melhor de agrupar mudanças que seja melhor para o caso de precisar retroceder? Se sim, faça o agrupamento de mudanças para um commit com isso em mente.
Use uma mensagem curta e apropriada : Prefira mensagens curtas e acertivas. Elas devem em poucas palavras permitir se lembrar ou advinhar o que foi feito. Normalmente, mensagens que relatam o porquê das modificações são assim. Se um commit precisar de uma mensagem longa demais, então é porque ele agrupa modificações divisíveis.
Use o tempo verbal como se fosse um comando : Recomenda-se usar o tempo verbal no presente da segunda pessoa (ele/ela): faz, corrige, remove, muda, fatora, rescreve, transfere, copia, acrescenta, modifica.
Adote o idioma plenamente : Adotar o idioma plenamente, com palavras acentuadas e sinais de pontuação facilita bastante quando for necessário fazer buscas nos textos das mensagens, pois só existe um jeito certo para a grafia das palavras.
Para fazer merge request visite:
https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/merge_requests.
Clique no botão New Merge Request para criar um novo MR. Detalhe no
campo descrição todas as contribuições enviadas com o ramo que você
submeteu para a avaliação, informe também qual o issue esse ramo
refere-se com #NumeroIssue
isso garante que as atualizações feitas no
MR também serão reportadas no issue correspondente. Escolha dentre os
mergers do projeto aquele que foi designado para você.
Quando o seu MR não for aceito, o merger vai deixar descrição das correções a serem feitas na página do seu MR. Todo MR tem um número correspondente, como os issues. Quando fizer as correções por ele apontadas, comente na página do MR que o ramo está pronto para incorporação novamente.
Após aceito o MR, ou seja, suas contribuições tiverem sido incorporadas
ao ramo devel
, deve-se fechar o issue que originou o MR. Caso tenha
colocado na descrição do MR a indicação do issue com #NumeroIssue
,
apenas vá até o issue
(https://gitlab.c3sl.ufpr.br/pet-estatistica/labestData/issues/NumeroIssue)
e clique em Close issue, caso contrário indique como comentário do
issue qual MR que incorpora as contribuições por ele indicadas, faça
isso com !NumeroMR
. Com o issue finalizado, deve-se então remover o
ramo criado para desenvolvimento do trabalho, faça isso com
# Atualiza todos os ramos conforme versão remota git pull # Mude para o ramo baby git checkout baby # Remova o ramo de desenvolvimento local git branch -d seunome123 # Remova o ramo de desenvolvimento do GitLab git push origin :seunome123
Certifique-se de que o ramo de desenvolvimento do issue foi realmente incorporado ao devel para então realizar esses procedimentos. Feito isso retorna-se à seção Criar ramo para Desenvolvimento realizando todo o roteiro descrito semanalmente até que se finalize todas as issues compreendidas na Milestone correspondente.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.