Desenvolvimento

From The Document Foundation Wiki
Jump to: navigation, search


Efetuando sua primeira compilação do LibreOffice

Efetuando sua primeira compilação bem sucedida do LibreOffice pode ser uma tarefa intimidante e difícil. Encontre um passo a passo que o orientará em sua primeira compilação pronta na página Como compilar.

Como se envolver

Desenvolvedores e usuários podem contribuir para o desenvolvimento do LibreOffice de muitas maneiras, e todos são bem-vindos ao projeto. Usuários, por exemplo, podem ajudar testando versões beta do programa, relatando e testando erros, escrevendo documentações, contribuindo com modelos, com a arte, com o dicionário de ortografia, com o dicionário de sinônimos, etc. Por fim, mas não menos importante, pode contribuir promovendo o LibreOffice, ajudando na revista brasileira, por exemplo.

Já os desenvolvedores podem ajudar a melhorar o código base, por exemplo. O código-base pode ser intimidatório no início, mas a documentação está melhorando, além de você ter a assistência do time de desenvolvedores existente. Para uma noção da complexidade do LibreOffice, veja a página Visão Geral do Código (em inglês) para lhe ajudar a ter uma ideia dos diretórios e repositórios usados.

Aqui também tem uma lista de Perguntas frequentes.

Você pode acompanhar o desenvolvimento vendo a lista de todos os commits em tempo real (cortesia de cia.vc).

Relatando problemas

Relatar erros, conferi-los e verificar se continuam existindo é uma contribuição muito valiosa para o projeto. Aqui tem a explicação sobre como informar novos erros/problemas.

Encontre sua primeira tarefa: hacks fáceis

Para minimizar a barreira inicial para novos contribuidores, o time do LibreOffice elaborou uma lista de hacks fáceis. Ela foi criada para lhe ajudar a encontrar uma primeira tarefa. Você também pode encontrar uma lista de hack fáceis no rastreador de erros do LibreOffice: hacks fáceis no Bugtracker. Claro que existem outros defeitos ou melhorias lá: itens em aberto.

Lista de melhorias e funcionalidades ausentes

Além da página Wiki sobre hacks fáceis, várias outras listas de melhorias e funcionalidades ausentes foram criadas:

  • Existe uma lista de ideias malucas que contém alterações drásticas assim como outras funcionalidades ausentes.
  • Uma página dedicada a funcionalidades ausentes e melhorias que estão relacionadas às necessidade de grandes empresas, onde a gerência de TI tem alguns desafios na distribuição, organização e suporte. Nós listamos nesta página o que as empresas nos contaram sobre o que adorariam ver no LibreOffice. Se quer o seu chefe feliz, ajude-nos a fazer isso!
  • Uma página que acolhe ideias para melhorias na experiência do usuário comum está em Melhoria dos padrões da IU.
  • Uma página que lista melhorias e funcionalidades ausentes extremamente básicas.
  • Uma lista em que os usuários expressam suas necessidades de que certas melhorias sejam feitas: Vote pela melhoria.

Preparando patches

Primeiro de tudo, faria mais sentido seguir o Estilo de Codificação do OpenOffice.org e as convenções de código (como esquemas de nomeação variável, etc). Para preparar um patch que você pode enviar para a lista de discussão de desenvolvimento, vamos supor que você começou com um ramo principal não modificado. Os passos são os seguintes:

  • Trabalhar no código para o conteúdo de seus corações (se você planeja algo maior, considere usar os ramos de funcionalidades)
  • Mandar suas mudanças locais para o git. A primeira opção adiciona todos os arquivos modificados, enquanto a segunda opção permite você selecionar quais arquivos serão submetidos:
git commit -a

 ... ou ...

git add <file1> <file2> ...
git commit

Quando você digita uma mensagem de envio, use a primeira linha como um resumo conciso das suas mudanças. A segunda linha permanece vazia e, iniciando na terceira linha, você pode explicar como e o que foi modificado por quais razões.

  • Criar um arquivo de patch que você deseja enviar. Se estiver em um repositório você pode usar o git diretamente para pegar, por exemplo, a última alteração no seu ramo como um arquivo diff com:
git format-patch HEAD~1

Se você fez mudanças mais amplas entre múltiplos repositórios, você pode pegar os patches para todos estes repositórios de uma vez com:

./g format-patch --suffix=.@REPO@.patch -o/home/me/somedir/to_save_my_patches_in origin/master..HEAD

Alternativa: Oferecendo ramos git para puxar a partir deles

O LibreOffice está sendo desenvolvido usando o git, e é claro que podemos usar todos os maravilhosos recursos que o git oferece. Por exemplo, como as pessoas podem preparar um ramo git clonado que os desenvolvedores podem puxar patches a partir deles. Se você pretende fazer isso, seria sábio coordenar com um desenvolvedor antecipadamente se ele se sente confortável em fazê-lo.

Usando Git para o desenvolvimento do LibreOffice

Git é um Sistema de Controle de Versão Distribuído (Distributed Version Control System - DVCS). É um sistema muito poderoso e simples, mas se você não estiver familiarizado com DVCS, pode ser confuso. Felizmente, há grandes recursos na Web para aprender sobre o Git. Se você não estiver familiarizado com ele, você deve visitar o site http://git-scm.com/. O resto deste artigo assumirá um conhecimento básico de trabalho do Git.

Devido ao grande tamanho do projeto, o código-fonte do LibreOffice é distribuída entre 19 distintos repositórios Git. Isso cria novos desafios, mesmo para usuários ávidos do git.


./bin/g

Um dos principais desafios é que muitas vezes você vai encontrar-se na necessidade de executar o mesmo comando git em todos os 19 repositórios. A raiz do repositório contém um pequeno utilitário chamado g, localizada no ./bin/g (os caminhos são dados relativos à raiz do seu repositório GIT do LibreOffice), ou em ./g se você estiver usando a versão bootstrap.

A maioria dos comandos que você deve digitar como git xxxx, pode ser escrito como ./bin/g xxxx, o que significa 'execute git xxxx em cada repositório contido em ./clone/'.

Por padrão, para a maioria dos comandos no git, se ocorrer um erro ao executar o comando em qualquer um dos repositórios git do LibreOffice, o ./bin/g irá parar e não vai aplicar o comando sobre o resto dos repositórios. Para sobrepor este comportamento, você pode digitar ./bin/g -f xxxx.

Se você estiver usando a versão de inicialização, você pode simplesmente substituir todas as instâncias. / Bin / g com. / G, e acima de tudo ainda se mantém.


Simplificando o uso do ./bin/g

O ./bin/g não está normalmente em seu PATH. Você poderia, claro, colocá-lo em seu PATH, mas que iria impedir que você tenha várias cópias do código base. Devido ao tempo que leva para fazer uma limpeza completa na compilação, eu prefiro ter uma segunda cópia dos repositórios, onde eu faço a maioria das mudanças recentes fora do desenvolvimento de ponta.

O ./bin/g não estar no seu PATH, faz o comando digitado complicado e propenso a erros. O pequeno script a seguir - que é para ser colocado em um diretório que está no seu PATH, sob o nome find-lo-bin - fornece uma solução para esse problema:


#!/bin/bash

current_dir=`pwd`
while [ ${current_dir} != "/" -a -d "${current_dir}" -a ! -d "${current_dir}/.git" ] ;
do
current_dir=$(dirname "${current_dir}")
done
if [ $(basename $(dirname ${current_dir})) = "clone" ] ; then
current_dir=$(dirname $(dirname "${current_dir}"))
fi
echo "${current_dir}/bin"
unset current_dir


Agora você pode adicionar este script a sua lista de alias (no seu .bashrc, por exemplo):

alias g='$(find-lo-bin)/g'


Com isso no lugar, agora você pode digitar 'g xxxx' enquanto você estiver em algum diretório dentro do raiz do repositório do LibreOffice.

Outra limitação do ./bin/g é que ela só se aplica para os repositórios git em ./clone/ e não na raiz do repositório git em si. Mais frequentemente do que nunca, você vai se encontrar digitando git xxx && ./bin/g xxx.


O seguinte pequeno script, chamado 'ga', fornece um encapsulamento para isso:


#!/bin/bash

cd $(find-lo-bin)/..
if [ "$1" = "-f" ] ; then
shift
git "$@"
./bin/g -f "$@"
else
git "$@" && ./bin/g "$@"
fi
cd - > /dev/null

Procurando

Você pode usar o git grep em vez de grep como ele é muito mais rápido em grandes árvores-fonte apenas olhando para os arquivos sob o controle de revisão. E você pode usar o g grep ou ga grep para pesquisar em todos os repositórios git de uma vez.

Outra alternativa é usar o opengrok, uma ferramenta Web, que pode ser muito mais rápido do que procurar em sua própria máquina.


Gerenciando os ramos git

Verificando os ramos atuais

Para ver quais os ramos no seu repositório atualmente está atualizado, digite:


~/loroot $ ./g branch


Estas listas do ramo local para cada repositório e colocar um '*' na frente de um atualmente ativo. Cada repositório deve relatar o mesmo ramo como ativo.

Adicionando -r após o comando branch irá te mostrar os ramos que estão disponíveis nos repositórios remoto (por exemplo, a lista dos ramos de funcionalidades disponíveis).


Trocando para um ramo de funcionalidade

Vamos criar um ramo de funcionalidade 'feature/slicebread' em todos os repositórios git com base em origin/master, que te permite desenvolver com segurança uma nova funcionalidade:


~/loroot $ ./g checkout -b feature/slicebread origin/master


Se você exibir novamente o ramo ativo, todos os repositórios devem relatar 'feature/slicebread'.

Se você quiser mudar para um ramo de funcionalidade existente, ao invés de criar um novo, faça:


~/loroot $ ./g -f checkout -b feature/slicebread origin/feature/slicebread


Isso irá criar um ramo local 'feature/slicebread' que acompanha o ramo remoto feature/slicebread. A opção -f força o bin/g para passar por todos os repositórios sem abortar, mesmo que alguns repositórios não tenham o ramo.

Voltando: Se você quiser voltar para o ramo master e excluir seu ramo local, certifique-se que você não tem quaisquer alterações não publicadas em seus repositórios, então primeiro volte para o master, e então exclua o seu ramo local feature/slicebread.


~/loroot $ ./g checkout master
~/loroot $ ./g -f branch -D feature/slicebread


Hackeando e publicando (commit) em um ramo de funcionalidade

Agora você pode hackear e compilar como você deseja. Não tenha vergonha de publicar o seu trabalho. Estas publicações são puramente local e não será visível até que você enviá-los. Você sempre pode re-organizar ou fundir algumas publicações mais tarde, se quiser apresentar um histórico limpo. Cada submissão deveria conter um conjunto de mudanças que estão relacionados uns aos outros e ser descrita com clareza na mensagem de log. A primeira linha da mensagem de log devem ser um resumo conciso da mudança (80 caracteres ou menos), então pule uma linha e insira uma descrição mais detalhada conforme a necessidade.

Agora você tem implementado sua nova funcionalidade ou tem feito alguns progressos e deseja obter algum retorno.

Primeiro, desde que o ramo principal (master) provavelmente mudou desde quando você ramificou para fora dele para o seu ramo de funcionalidade, você deve re-basear suas alterações, de modo que elas se apliquem no atual ramo principal HEAD (master's HEAD).

Para re-basear, você precisa ter certeza de que você publicou tudo o que importa e limpou o seu repositório, para que não haja alterações "pendentes". Depois, volte para o ramo principal com:

~/loroot $ ./g checkout master

Atualize seu ramo principal

~/loroot $ ./g pull -r

Volte para o seu ramo de funcionalidade

~/loroot $ ./g checkout feature/slicebread

e re-baseie

~/loroot $ ./g rebase origin/master

Se houver conflitos que você precisa resolvê-los manualmente e continuar re-baseando até estarem feito.

Agora, é hora de publicar. Há dois casos.

Se você não tiver um conjunto de repositórios git para empurrar essas mudanças, então você quer preparar um conjunto de patches para poder publicá-las na lista Dev@ para revisão.

~/loroot $ ./g format-patch --suffix=-@REPO@.patch --output-dir=<where_you_want> master..HEAD


Isso irá gerar um arquivo por publicação sufixado pelo nome do repositório, no diretório que você especificou. Você pode anexá-los a um e-mail para a lista de discussão.

Se você tiver acesso de publicar em um conjunto de repositório git, então

~/loroot $ ./g push origin feature/slicebread


Há uma abundância de excelentes tutoriais, livros e até vídeos sobre como usar o git. Você é fortemente encorajado a vê-los. O Ambiente de Desenvolvimento do LibreOffice tem 20 repositórios git que são logicamente um, mas precisa ser cuidados individualmente (daí o script g e ga).


Hackeando e publicando em um ramo estável

Ramos estáveis são criados a partir do principal ou de outro ramos estáveis ​​para estabilizar a base de código para o lançamento e atualizações de manutenção. Há apenas algumas regras durante a fase beta:

  • Permitido qualquer correções de bugs
  • Permitido características finais que são aprovados pelo Comitê Gestor (em inglês)
  • Permitida qualquer alteração nas traduções

Existem regras mais rigorosas durante a fase de Candidato a Lançamento (Release Candidate):

  • Permitida salvar correções que são revisadas por outra pessoa, veja abaixo
  • Permitida alterações nas traduções; é recomendado pedir pela revisão na lista de discussão l10n@ nativa

Por favor, não publique os reparos diretamente durante a fase RC. Em vez disso, por favor, pergunte a outro desenvolvedor para revisão na lista de discussão libreoffice@lists.freedesktop.org, e-mail pessoal, no IRC ou através da entrada de bugs relacionados. A correção deve ser publicada pelo revisor usando:

git commit -s --author='Author name <author@mail.address>'


Redefinindo seu repositório modificado para um repositório "vanilla" antigo

~/loroot $ bin/g reset --hard origin/master

Descartará todas as alterações locais (se publicadas ou não) e redefine o ramo atual em que você está para o que está no repositório remoto.


Obtendo e usando um acesso de publicação

A fim de obter o acesso de publicação que você precisa para ser "promovido". Uma vez que você enviou patches e se reconheceu, este não será um problema, mas é melhor esperar até que lhe seja perguntado. Uma vez que você foi convidado (ou pediu para alguém patrocinar você), você precisa obter uma conta.


Orientações Gerais de Programação

sal_Bool deve ser usado somente quando se trata de UNO, e bool é preferencial em caso contrário.


Trabalhando em seções específicas do LibreOffice

automake/configure

Como implementado atualmente, existem dois arquivos configure.in principais, um no diretório raiz da compilação, e um no subdiretório do libreoffice. Quaisquer mudanças importantes devem ser feitas para ambas, como o da raiz está previsto para a remoção, uma vez que todas as "patch-sets" atuais no sistema foram fundidas na base do código principal.

Os argumentos padrão no sistema de compilação estão atualmente em <loroot>/build/distro-configs.

As atuais opções de configurações (em inglês) de cada subnível do configure.in e também quais opções estão somente no nível superior.

Hackeando o configure.in

Depurando

Desenvolvimento / Notas de Hacking

TODO: add syntaxhighlight