... | ... | @@ -2,8 +2,9 @@ Cada projeto deve ter uma pessoa responsável e uma pessoa capacitada para orien |
|
|
|
|
|
Está em desenvolvimento no CTA um modelo de organização dos projetos. Nele constará o que, segundo nossa experiência, são a melhores práticas de documentação e organização de projetos. Poderão ser inclusos outros softwares de documentação e organização, além do próprio site do CTA.
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
### Diretrizes Básicas dos Projetos
|
|
|
## Diretrizes Básicas dos Projetos
|
|
|
|
|
|
Os projetos do CTA devem possuir:
|
|
|
|
... | ... | @@ -13,41 +14,70 @@ Os projetos do CTA devem possuir: |
|
|
* Execução (das tarefas): Definição clara de ponto de conclusão das tarefas; e Uso de ferramentas livres;
|
|
|
* Registro (memória): Documentação, Organização e Licenças permissivas
|
|
|
|
|
|
### Documentação
|
|
|
## Documentação
|
|
|
|
|
|
A documentação deve ser realizada no repositório git de cada projeto. Nele se tem o espaço das wikis, onde se registram informações pertinentes sobre o projeto e conteúdos associados, o repositório de arquivos, onde ficam salvos as licenças, arquivos de execução, esquemáticos e guias de uso e montagem, e as tarefas (issues), onde são registras as atas das reuniões, as tarefas e os cadernos de laboratório. Saiba mais sobre o git [aqui](https://pt.wikipedia.org/wiki/Git).
|
|
|
Cada repositório de projeto está associado a um grupo. Para se ter permissão para editar o projeto, é preciso ser membro do grupo. Por exemplo, o projeto "CTA" está dentro do grupo "Suporte CTA".
|
|
|
|
|
|
Para explicar um pouco mais de como a documentação funciona, será explicado a função de cada parte do git pensando no exemplo de um projeto de um amplificador de guitarra.
|
|
|
|
|
|
**Wiki**
|
|
|
### O que é o GIT?
|
|
|
|
|
|
As wikis são destinadas a conteúdo informativo sobre o projeto, conteúdo que é importante para que seja compreendido, mas que não é essencial para o seu uso, execução ou montagem. Nela então estará a explicação de o que é um amplificador de guitarra, seu funcionamento, qual o modelo escolhido, qual a etapa de desenvolvimento, qual o objetivo final, com quais outros projetos se relaciona, etc.
|
|
|
O [GIT](https://pt.wikipedia.org/wiki/Git) é um sistema de controle de versões distribuído, usado principalmente para software e arquivos de textos. Além do controle de versões o git também tem um sistema de tarefas, wikis, e muitas outras ferramentas que podem ser usadas para a gestão de um projeto. O site CTA é um sistema GIT instalado nos servidores do IF/UFRGS, por isso temos todas essas ferramentas ao nosso dispor. Abaixo estão descritas algumas partes do GIT e como a usamos no CTA.
|
|
|
|
|
|
**Repositório (arquivos)**
|
|
|
### Usuários, Grupos e Projetos
|
|
|
|
|
|
__Usuário__: é uma conta, representa uma pessoa, por isso tem e-mail e @ próprios; cada usuário tem, automaticamente, uma página prórira onde ficam registradas as informações de atividades no site; exemplo: @renanrs .
|
|
|
__Grupo__: pode ter uma ou mais pessoas, mas representa um tema, um grande projeto, da onde vários outros projetos e atividades terão origem; cada grupo tem apenas uma página, e nenhuma ferramenta, nessa página estão listados os projetos da página e uma breve descrição do grupo. Exemplo: [CosmicPampa](https://git.cta.if.ufrgs.br/CosmicPampa)
|
|
|
__Projeto__: um projeto pode ser criado diretamente da página de um usuário, ou de um grupo; no CTA os projetos devem ser preferencialmente criados a partir de um grupo, não de um usuário; dentro de cada projetos existem diversas ferramentas que podem ser usadas para o o desenvolvimento do projeto, como wikis e tarefas; exemplo: [Suporte CTA](https://git.cta.if.ufrgs.br/suporte-cta/cta)
|
|
|
|
|
|
Se vocês já tem conta no site do CTA, ou no LIEF do IF/UFRGS, então você já tem um usuário no nosso GIT - caso contrário, nos mande um e-mail pedindo para criar conta! Você pode criar um projeto direto do seu usuário, ou você pode criar um grupo. Os grupos tem como objetivo reunir pessoas envolta de um mesmo projeto ou conjunto de projetos. Dentro de cada grupos é possível ter vários "projetos", que são várias etapas ou partes de um mesmo grande projeto, ou são diferentes projetos associados por um mesmo assunto. Por exemplo, o grupo "CTA" é aquele das pessoas que estão envolvidas com o CTA, e dentro desse grupo tem o projeto chamado "Suporte CTA", onde estão concentradas as informações sobre a organização do CTA, onde estão as atas de reuniões e as discussões sobre o CTA de maneira ampla. Outro exemplo é o Grupo [SACADA](https://git.cta.if.ufrgs.br/SACADA), nesse grupos estão as várias pessoas envolvidas com diferentes etapas do desenvolvimento do SACADA, e dentro desse grupo estão vários projetos, que são partes diferentes do grande projeto SACADA, por exemplo: SACADA Pro Hardware, identidade visual do SACADA, sacada-python, etc.
|
|
|
|
|
|
Cada projeto tem, dentro de si, um conjunto próprio de wikis, de tarefas, de repositórios, etc. Isso significa que se for criada uma página Wiki no projeto sacada-python, essa wiki não vai aparecer no projeto SACADA Pro Hardware, mesmo que os dois estejam no mesmo grupo! Da mesma forma, a wiki não irá aparecer em projetos de outros grupos. O mesmo vale para a atualizações nos repositórios e tarefas. O que é feito em um projeto fica somente nesse projeto.
|
|
|
|
|
|
### Repositório (arquivos)
|
|
|
|
|
|
Para projetos de software e de hardware, aqui devem estar todos os arquivos essenciais para o uso, estudo, modificação e distribuição do projeto, inclusive as licenças. Não é preciso colocar no repositório o referencial teórico, ou longas explicações sobre a motivação do projeto ou as escolhas técnicas.
|
|
|
|
|
|
O repositório é uma grande pasta onde os arquivos são guardados. O git tem um sistema de versionamento para arquivos texto. Isso significa que cada novo arquivo de texto submetido, apenas as alterações no texto em relação a versão anterior são salvas, então é fácil desfazer alterações e voltar a versões anteriores. Outra facilidade é a possibilidade de se fazer um ramo (*branches*). Quando um ramo de um projeto é criado, é possível que o desenvolvimento dele ocorra em dois ramos paralelos, e que, ao final, esses ramos sejam fundidos (*merge*) e as alterações dos dois ramos sejam somadas. Note que essa função funciona para arquivos de texto, outros formatos, como desenhos e esquemáticos não tem controle de versionamento. Isso não significa, porém, que o repositório não deve ser usado para eles. Pelo contrário, o repositório é o lugar de todos os arquivos necessário para o uso, funcionamento e montagem do projeto. A ideia é que uma pessoa interessada em reproduzir o projeto possa *clonar* o repositório e, a partir dos arquivos dele, reproduzi-lo.
|
|
|
|
|
|
No exemplo do amplificador de guitarra, estariam no repositório, devidamente organizados em pastas, os códigos do *firmware*, digamos, do Arduino, os arquivos dos esquemáticos da placa de circuito, incluindo os arquivos usados para sua impressão (os gerbers), também estariam aí os desenhos técnicos para a caixa de proteção (se for feita a mão, desenhos com detalhes de cada peça, se for impressão 3D, os arquivos CADs da peça) e arquivos de texto com lista de materiais, componentes, e guias de montagem, ou execução, para cada versão ou parte específica.
|
|
|
Por exemplo, em um projeto para a construção de um amplificador de guitarra, estariam no repositório, devidamente organizados em pastas, os códigos do *firmware*, digamos, do Arduino, os arquivos dos esquemáticos da placa de circuito, incluindo os arquivos usados para sua impressão (os gerbers), também estariam aí os desenhos técnicos para a caixa de proteção (se for feita a mão, desenhos com detalhes de cada peça, se for impressão 3D, os arquivos CADs da peça) e arquivos de texto com lista de materiais, componentes, e guias de montagem, ou execução, para cada versão ou parte específica.
|
|
|
|
|
|
Todo repositório git tem um arquivo chamado "README.MD"; o conteúdo desse arquivo aparece na página inicial do repositório, então é essencial que nele esteja uma visão geral do projeto, explicando que informações estão no repositório, quais estão nas wikis e quais estão nas tarefas.
|
|
|
|
|
|
Pode parecer confuso de início, até porque o repositório não pode ser alterado diretamente do site, é preciso *clonar* o projeto para o computador, depois subi-lo de volta para o repositório. Veja mais dicas de uso do repositório [aqui](https://githowto.com/pt-BR), ou [aqui](http://rogerdudler.github.io/git-guide/index.pt_BR.html).
|
|
|
|
|
|
Obs. 1: sempre disponibilize os arquivos editáveis; por exemplo, arquivos .pdf e .stl não são editáveis, logo o projeto não pode ser modificado, por isso a importância de disponibilizar também a versão .txt/.odt e os cads.
|
|
|
Obs. 2: disponibilize os arquivos em formatos abertos, ou seja, formatos que abrem em *softwares* livres; por exemplo, o arquivo .docx é editável, mas é um formato de arquivo do Word, um *software* proprietário; sua versão livre seria o .odt, do libre Office.
|
|
|
|
|
|
**Tarefas (Issue)**
|
|
|
Obs.2: Projetos de estudo teórico ou de organização usam menos o repositório, de maneira que os conteúdos essenciais provavelmente estarão nas Wikis.
|
|
|
|
|
|
### Wikis
|
|
|
|
|
|
As wikis são destinadas a conteúdo informativo sobre o projeto, conteúdo que é importante para que seja compreendido. Por exemplo, nela estará a explicação de o que é um amplificador de guitarra, seu funcionamento, qual o modelo escolhido, qual a etapa de desenvolvimento, qual o objetivo final, com quais outros projetos se relaciona, etc.
|
|
|
|
|
|
No caso de grupos de estudo, as wikis são um bom lugar para registras resumos, ou até produzir conteúdos inéditos, sobre os assuntos estudados.
|
|
|
|
|
|
No caso de projetos de organização interna, como o Suporte CTA, as wikis são essenciais para descreverem como a gestão do grupo funciona, informações de contatos, documentação de eventos, etc.
|
|
|
|
|
|
### Tarefas (Issue)
|
|
|
|
|
|
As tarefas tem como objetivo inicial o registro de tarefas e de problemas, falhas, dos sistemas. Elas também podem ser usadas como fóruns de discussão, de uma maneira mais limitada, ou também como cadernos de laboratório. Os cadernos de laboratório são muito importantes para que se registre o andamento do projeto, registrando erros e falhas, e também para registrar testes, ou para o registro do acompanhamento da evolução de algum sistema, digamos por exemplo, o crescimento de bactérias.
|
|
|
|
|
|
Para a organização das tarefas, sugerimos fortemente o uso das etiquetas (tags), elas ajudam a organizar e classificar as tarefas, facilitando que sejam encontradas. Para o nosso exemplo em específico, alguns exemplos de etiquetas são: "reunião", "hardware", "caixa", "circuito", "firmware", "testes", "montagem", "versão0.1", "oficina", etc. As etiquetas podem ser usadas conjuntamente. Uma reunião sobre a versão 0.1 do protótipo pode ser etiquetada com "reunião" e "versão0.1". Por exemplo, as reuniões gerais do CTA são etiquetadas com "reunião', de maneira que basta clicar nesse [link](https://git.cta.if.ufrgs.br/suporte-cta/cta/issues?scope=all&utf8=%E2%9C%93&state=all&label_name[]=reuni%C3%A3o) para acessar todas as reuniões passadas.
|
|
|
|
|
|
As tarefas tem como objetivo inicial o registro de tarefas, evidente, e de problemas, falhas, dos sistemas. Elas também podem ser usadas como fóruns de discussão, de uma maneira mais limitada, ou também como cadernos de laboratório. Os cadernos de laboratório são muito importantes para que se registre o andamento do projeto, registrando erros e falhas, e também para registrar testes, ou para o registro do acompanhamento da evolução de algum sistema, digamos por exemplo, o crescimento de bactérias. Para a organização das tarefas, sugerimos fortemente o uso das etiquetas (tags), elas ajudam a organizar e classificar as tarefas, facilitando que sejam encontradas. Para o nosso exemplo em específico, alguns exemplos de etiquetas são: "reunião", "hardware", "caixa", "circuito", "firmware", "testes", "montagem", "versão0.1", "oficina", etc. As etiquetas podem ser usadas conjuntamente. Uma reunião sobre a versão 0.1 do protótipo pode ser etiquetada com "reunião" e "versão0.1".
|
|
|
Um exemplo de tarefa pode ser "Desenhar o circuito da placa de amplificação". Note que uma tarefa é sempre uma ação, e a tarefa deve ter objetivos realistas e destacados, para que se entenda com facilidade sua finalidade. Nela serão registradas como o problema foi resolvido, ou as etapas do desenvolvimento. É essencial que as tarefas sejam atribuídas a alguém, e que tenham uma data limite para serem entregues. Essas são ferramentas que o git disponibiliza que contribuem muito para a organização do projeto.
|
|
|
|
|
|
### Ferramentas livres - Hiperobjetos
|
|
|
Para um grupo de estudo, pode ser feita uma tarefa para cada tema, por exemplo "REA", ou para textos em específico.
|
|
|
|
|
|
## Ferramentas livres - Hiperobjetos
|
|
|
|
|
|
A política de desenvolvimento do CTA está baseada no amplo uso de ferramentas livres. Sempre que possível, defendemos que o projeto deve ser desenvolvido com as opções *open source* das ferramentas. Por exemplo, os textos podems er esscritos em editores como o gedit, ou no Libre Office. As peças 3D podem ser desenhadas no FreeCAD, e as imagens desenhadas no Inkscape. Nem sempre a máquina que temos a disposição é um *hardware* aberto e livre, mas buscamos que seja possível fabricar o projeto usando o máximo de máquinas livres possíveis. Isso significa que o projeto pode ser desenvolvido num computador com windows e ser fabricado numa impressora proprietária, mas que deve prioritariamente funcionar em sistemas operacionais livres, como o Debiam, e que devem poder ser impressos em versões livres de uma impressora 3D. Por vezes, isso não será possível, como no caso do uso de máquinas de corte a LASER; como não há versões livres disponíveis, será sempre feito em uma máquina proprietária. Mesmo assim, os arquivos disponibilizados devem estar em formato aberto.
|
|
|
No exemplo do amplificador, o microcontrolador usado poderia ser o Arduino, seu circuito ser desenhado no KiCAD ou no Fritzing, suas peças desenhadas no FreeCAD.
|
|
|
Algumas ferramentas livres do CTA e tutoriais delas já estão registradas [aqui](http://cta.if.ufrgs.br/projects/suporte-cta/wiki/Tutoriais).
|
|
|
Um aprofundamento filosófico sobre essa questão nos leva ao conceito de Hiperobjetos, conceito que guia as ações do CTA. O assunto é abordado mais profundamente em no texto [Ciência aberta: dos hipertextos aos hiperobjetos](http://livroaberto.ibict.br/bitstream/1/1060/1/Ciencia%20aberta_questoes%20abertas_PORTUGUES_DIGITAL%20(5).pdf), escrito por Rafael Pezzi.
|
|
|
|
|
|
### Licenças
|
|
|
## Licenças
|
|
|
|
|
|
Licenças permissivas são licenças que permitem que a obra, documentação, texto, imagens, música, etc. seja livremente usada, modificada e redistribuída. Algumas licenças exigem o direito a citação da pessoa ou grupo autora do projeto, outras não. No CTA adotamos como licenças padrões as seguintes:
|
|
|
|
... | ... | @@ -59,13 +89,13 @@ Licenças permissivas são licenças que permitem que a obra, documentação, te |
|
|
|
|
|
----
|
|
|
|
|
|
### Encontros periódicos
|
|
|
## Encontros periódicos
|
|
|
|
|
|
É aconselhável que cada projeto tenha pelo menos um encontro por mês e que este encontro seja sempre registrado nas tarefas do próprio projeto. Como especificado no [modelo de gestão de projetos do CTA](http://cta.if.ufrgs.br/attachments/download/2753/Gerenciamento_de_projetos_do_CTA_08_Julho_2016.odp .
|
|
|
|
|
|
Mais informações sobre os encontros periódicos podem ser encontrados no item abaixo [Dinâmicas de Reuniões e Organização, em Gestão do CTA.
|
|
|
|
|
|
### Papéis
|
|
|
## Papéis
|
|
|
|
|
|
* *Mantenedor do projeto:* Tem visão panorâmica sobre o projeto e atua com papel de liderança na equipe. É responsável por marcar reuniões e registros no fórum e motivar a equipe, o que exige ter especial cuidado com cada pessoa envolvida. Não é autoridade do projeto, é um(a) facilitador(a) e também atua como membro da comunidade. Posto pode ser rotativo (~ 6 meses). Gestão tem data de início e fim.
|
|
|
* *Zelador de Projeto:* Responsável pela organização das atividades do projeto, como noção dos prazos e andamento. Cuida das reuniões (pauta, chamada, registro)e deve ter especial atenção à organização no mundo digital (documentação). Pode ter apoio dos demais para atingir seus objetivos.
|
... | ... | @@ -74,7 +104,7 @@ Mais informações sobre os encontros periódicos podem ser encontrados no item |
|
|
|
|
|
Leia mais em [orientações iniciais para o projeto piloto Hackatona longa duração CTA](http://cta.if.ufrgs.br/attachments/download/5730/Orienta%C3%A7%C3%B5es_Iniciais_Hackatona_CTA_2018-2019.pdf)
|
|
|
|
|
|
#### Criar um projeto
|
|
|
### Criar um projeto
|
|
|
|
|
|
Caso você queira propor um novo projeto, esteja ciente de que todos os projetos desenvolvidos no CTA devem ser documentados publicamente nesse repositório sob licenças permissivas. Para propor um novo projeto, siga os seguintes passos:
|
|
|
|
... | ... | @@ -85,7 +115,7 @@ Caso você queira propor um novo projeto, esteja ciente de que todos os projetos |
|
|
|
|
|
---
|
|
|
|
|
|
### Publicações acadêmicas relativas ao projeto
|
|
|
## Publicações acadêmicas relativas ao projeto
|
|
|
|
|
|
Para além da documentação padrão no site do CTA, é indicado à pessoa mantenedora do projeto planejar desde os primeiros passos a publicação em meios tradicionais do meio acadêmico, como os periódicos científicos.
|
|
|
|
... | ... | |