From c12f7dff9e99d197a36a60664c85bda37ac6c68f Mon Sep 17 00:00:00 2001 From: eduardocalil Date: Mon, 16 May 2016 12:14:09 -0300 Subject: [PATCH] Fix #451 atualizar readme (#455) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Alteração em processo do arquivo README.rst * Refat. Proc de instalação, Testes, Issues - Falta Intruções de tradução - Falta Melhores práticas * inclusão do link de atualização de arq estáticos * Termina a traducao do README * Faz ajustes no README --- README.rst | 284 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 199 insertions(+), 85 deletions(-) diff --git a/README.rst b/README.rst index e77962fa9..34f0db8d9 100644 --- a/README.rst +++ b/README.rst @@ -3,163 +3,277 @@ :alt: 'Stories in Ready' *********************************************** -SAPL - Legislative Process Support System +SAPL - Sistema de Apoio ao Processo Legislativo *********************************************** -This page brings together useful information on the current development of -**SAPL - Sistema de Apoio ao Processo Legislativo** (Legislative Process Support System). +Esta página reúne informações úteis sobre o desenvolvimento atual do SAPL. -That means all information presented here applies only to **version 3.1** and greater. +Isso significa que toda a informação aqui apresentada aplica-se apenas para a versão 3.1 e superior. -For more information about the the project as a whole and the current working version of the system (2.5) -please visit the `project page at Interlegis wiki `_. +Para obter mais informações sobre o projeto como um todo e a versão de trabalho +atual do sistema (2.5), visite a página do `projeto na Interlegis wiki `_. -Development Environment Installation -==================================== -* Install the following system dependencies (command bellow for Ubuntu):: +Instalação do Ambiente de Desenvolvimento +========================================= + +* Procedimento testado nos seguintes SO's: + + * `Ubuntu 16.04 64bits `_; + + * edite e incremente outros, ou ainda, crie outros readme's dentro do projeto para outros SO's e adicione o link aqui. + +Instalar as seguintes dependências do sistema:: +---------------------------------------------------------------------------------------- + +* :: sudo apt-get install git nginx python3-dev libpq-dev graphviz-dev graphviz \ - pkg-config postgresql postgresql-contrib pgadmin3 python-psycopg2 nodejs npm \ + pkg-config postgresql postgresql-contrib pgadmin3 python-psycopg2 \ + software-properties-common build-essential libxml2-dev libjpeg-dev \ + libssl-dev libffi-dev libxslt1-dev python3-setuptools curl + + sudo easy_install3 pip lxml - sudo ln -s /usr/bin/nodejs /usr/bin/node + sudo -i + curl -sL https://deb.nodesource.com/setup_5.x | bash - + exit + sudo apt-get install nodejs + sudo npm install npm -g sudo npm install -g bower -* Setup git, following the instructions in https://help.github.com/articles/set-up-git. +Instalar o virtualenv usando python 3 para o projeto. +----------------------------------------------------- + +* Para usar `virtualenvwrapper `_, instale com:: + + sudo pip install virtualenvwrapper + + mkdir ~/Envs + +* Edite o arquivo ``.bashrc`` e adicione ao seu final as configurações abaixo para o virtualenvwrapper:: + + export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3 + export WORKON_HOME=$HOME/.virtualenvs + export PROJECT_HOME=$HOME/Envs + source /usr/local/bin/virtualenvwrapper.sh + +* Saia do terminal e entre novamente para que as configurações do virtualenvwrapper sejam carregadas. -* Fork and clone this repository, following the instructions in https://help.github.com/articles/fork-a-repo. +Clonar o projeto do github, ou fazer um fork e depois clonar +------------------------------------------------------------ -* If you don't have pip installed then execute the following instructions: +* Para apenas clonar do repositório do Interlegis:: - sudo apt-get install python-pip python-dev build-essential - sudo pip install --upgrade pip - sudo pip install --upgrade virtualenv + cd ~/Envs + git clone git://github.com/interlegis/sapl -* Create a virtualenv using python 3 for the project and activate it. - If you use `virtualenvwrapper `_:: +* Para fazer um fork e depois clonar, siga as instruções em https://help.github.com/articles/fork-a-repo que basicamente são: - mkvirtualenv -p /usr/bin/python3 sapl + * Criar uma conta no github - é gratuíto. + * Acessar https://github.com/interlegis/sapl e clicar em **Fork**. -* Install python dependencies (run on the project root):: + Será criado um domínio pelo qual será possível **clonar, corrigir, customizar, melhorar, contribuir, etc**:: + + cd ~/Envs + git clone git://github.com/[SEU NOME]/sapl + +* As configurações e instruções de uso para o git estão espalhadas pela internet e possui muito coisa bacana. As tarefas básicas de git e suas interações com github são tranquilas de se aprender. + + +Criar o ambiente virtual de desenvolvimento para o SAPL +------------------------------------------------------- +* :: + + mkvirtualenv sapl -a $HOME/Envs/sapl -p /usr/bin/python3 + +Instalação e configuração das dependências do projeto +----------------------------------------------------- + +* **Acesse o terminal e entre no virtualenv**:: + + workon sapl + +* **Instalar dependências ``python``**:: pip install -r requirements/dev-requirements.txt -* Install bower dependencies (run on the project root):: +* **Configurar Postgresql**: + + * Acessar Postrgresql para criar o banco ``sapl`` com a role ``sapl``:: + + sudo su - postgres + + CREATE ROLE sapl LOGIN + ENCRYPTED PASSWORD 'sapl' + NOSUPERUSER INHERIT CREATEDB NOCREATEROLE NOREPLICATION; + + ALTER ROLE sapl VALID UNTIL 'infinity'; + + CREATE DATABASE sapl + WITH OWNER = sapl + ENCODING = 'UTF8' + TABLESPACE = pg_default + LC_COLLATE = 'pt_BR.UTF-8' + LC_CTYPE = 'pt_BR.UTF-8' + CONNECTION LIMIT = -1; + + \q + + * Se você possui uma cópia da base de dados do SAPL, essa é a hora para restaurá-la. + * Obs: no ambiente de desenvolvimento, a role deve ter permissão para criar outro banco. Isso é usado pelos testes automatizados. + * (caso você já possua uma instalação do postrgresql anterior ao processo de instalação do ambiente de desenvolvimento do SAPL em sua máquina e sábia como fazer, esteja livre para proceder como desejar, porém, ao configurar o arquivo ``.env`` no próximo passo, as mesmas definições deverão ser usadas) + +* **Configurar arquivo ``.env``**: + + * Criação da `SECRET_KEY `_: + + É necessário criar um projeto fake para extrair uma chave SECRET_KEY:: + + mkdir ~/Envs/temp + cd ~/Envs/temp + + django-admin startproject sapl_temp + + grep SECRET_KEY sapl_temp/sapl_temp/settings.py + + Copie a linha que aparecerá, volte para a pasta do projeto SAPL e apague sua pasta temporária:: + + cd ~/Envs/sapl + rm -R ~/Envs/temp + + * Criar o arquivo ``.env`` dentro da pasta ~/Envs/sapl/sapl/.env:: + + DATABASE_URL = postgresql://USER:PASSWORD@HOST:PORT/NAME + SECRET_KEY = Gere alguma chave e coloque aqui + DEBUG = [True/False] + EMAIL_USE_TLS = [True/False] + EMAIL_PORT = [Insira este parâmetro] + EMAIL_HOST = [Insira este parâmetro] + EMAIL_HOST_USER = [Insira este parâmetro] + EMAIL_HOST_PASSWORD = [Insira este parâmetro] + + * Uma configuração mínima para atender os procedimentos acima seria:: + + DATABASE_URL = postgresql://sapl:sapl@localhost:5432/sapl + SECRET_KEY = 'Substitua esta linha pela copiada acima' + DEBUG = True + EMAIL_USE_TLS = True + EMAIL_PORT = 587 + EMAIL_HOST = + EMAIL_HOST_USER = + EMAIL_HOST_PASSWORD = + + + +* Instalar as dependências do ``bower``:: ./manage.py bower install -* Install `PostgreSQL `_ if you haven't already. +* Atualizar e/ou criar a base de dados para refletir o modelo da versão clonada:: + + ./manage.py migrate + +* Atualizar arquivos estáticos:: -* Create a ``sapl`` role with: + ./manage.py collectstatic --noinput - - Password ``sapl`` - - The privilege ``can create databases`` - - A big expiration date (or infinite, using eg ``ALTER ROLE SAPL VALID UNTIL 'infinity';``) +* Subir o servidor do django:: -* Create a database ``sapl`` with owner ``sapl``. + ./manage.py runserver -* Either run ``./manage.py migrate`` (for an empty database) or restore a database dump. +* Acesse o SAPL em:: -* In ``sapl/sapl`` directory create one file called ``.env``. Write the following attributes in it: + http://localhost:8000/ - - DATABASE_URL = postgresql://USER:PASSWORD@HOST:PORT/NAME - - SECRET_KEY = Generate some key and paste here - - DEBUG = [True/False] - - EMAIL_USE_TLS = [True/False] - - EMAIL_PORT = [Set this parameter] - - EMAIL_HOST = [Set this parameter] - - EMAIL_HOST_USER = [Set this parameter] - - EMAIL_HOST_PASSWORD = [Set this parameter] +Instruções para Tradução +======================== -`Generate your secret key here `_ +Nós utilizamos o `Transifex `_ para gerenciar as traduções do projeto. +Se você deseja contribuir, por favor crie uma conta no site e peça para se juntar a nós em `Transifex SAPL Page `_. +Assim que for aceito, você já pode começar a traduzir. -Instructions for Translators -============================ +Para integrar as últimas traduções ao projeto atual, siga estes passos: -We use `Transifex `_ to manage the project's translations. -If you want to contribute, please setup an account there and request to join us at -the `Transifex SAPL Page `_. -Once your join request is accepted, you can start to translate. +* Siga as instruções em `Development Environment Installation`_. -To integrate the last translations on a working instance follow these steps: +* Instale `Transifex Client `_. -* Follow the instructions at `Development Environment Installation`_. +Aviso: -* Install `Transifex Client `_. + O Transifex Client armazena senhas em 'plain text' no arquivo ``~/.transifexrc``. -.. warning:: - The Transifex Client stores passwords in plain text on the file ``~/.transifexrc``. + Nós preferimos logar no site do Transifex por meio de redes sociais (GitHub, Google Plus, Linkedin) e modificar, frequentemente, a senha utilizada pelo client. - We personally prefer to log into Transifex website with social network credentials and change the password used for the client frequently. +* `Pull translations `_ ou `push translations `_ usando o client. Faça o Pull somente com o repositório vazio, isto é, faça o commit de suas mudanças antes de fazer o Pull de novas traduções. -* `Pull translations `_ or `push translations `_ using the client. Pull only on a clean repo, i.e. commit your changes before pulling new translations. +* Execute o programa com ``.manage.py runserver`` e cheque o sistema para ver se as traduções tiveram efeito. -* Run the program with ``.manage.py runserver`` and check the system to see the translations into effect. +Nota: -.. note:: - The browser language preference is used to choose the translations to display. + O idioma do browser é utilizado para escolher as traduções que devem mostradas. -General implementation guidelines -================================= -Best practices +Orientações gerais de implementação +=================================== + +Boas Práticas -------------- -* Use English for all the code, commit messages and project docs. +* Utilize a língua portuguesa em todo o código, nas mensagens de commit e na documentação do projeto. -* Commit messages following the standard 50/72 columns. Start every commit message with a verb in infinitive. For more info on this please check: +* Mensagens de commit seguem o padrão de 50/72 colunas. Comece toda mensagem de commit com o verbo no infinitivo. Para mais informações, clique nos links abaixo: - Http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html - Http://stackoverflow.com/questions/2290016/git-commit-messages-50-72-formatting -* Keep all code in standard PEP8 (without exceptions). +* Mantenha todo o código de acordo com o padrão da PEP8 (sem exceções). + +* Antes de todo ``git push``: + - Execute ``git pull --rebase`` (quase sempre). + - Em casos excepcionais, faça somente ``git pull`` para criar um merge. -* Before every ``git push``: - - Run ``git pull --rebase`` (almost always). - - In exceptional cases simply use ``git pull`` to produce a merge. +* Antes de ``git commit``, sempre: + - Execute ``./manage.py check`` + - Execute todos os testes com ``py.test`` na pasta raiz do projeto -* Before ``git commit``, always: - - Run ``./manage.py check`` - - Run all tests with ``py.test`` at the root of the project tree +Atenção: -.. attention:: - The database user ``sapl`` needs to have the permission ``create database`` in postgres for the tests to complete successfully + O usuário do banco de dados ``sapl`` deve ter a permissão ``create database`` no postgres para que os testes tenham sucesso -* If you're not part of the core team, fork the repo and submit pull requests. - All are welcome to contribute. Please make a separate pull request for each bugfix/new feature. +* Se você não faz parte da equipe principal, faça o fork deste repositório e envie pull requests. + Todos são bem-vindos para contribuir. Por favor, faça uma pull request separada para cada correção ou criação de novas funcionalidades. -* New features are subject to approval, since they may impact a lot of people. - We suggest you open an issue to discuss new features. That can be made in Portuguese, as well as in English. +* Novas funcionalidades estão sujeitas a aprovação, uma vez que elas podem ter impacto em várias pessoas. + Nós sugerimos que você abra uma nova issue para discutir novas funcionalidades. Elas podem ser escritas tanto em Português, quanto em Inglês. -Tests ------ +Testes +------ -* Write tests for all the functionality you implement. +* Escrever testes para todas as funcionalidades que você implementar. -* Keep the test coverage near 100%. +* Manter a cobertura de testes próximo a 100%. -* To run all tests activate your virtualenv and issue these commands - **at the root of the repository**:: +* Para executar todos os testes você deve entrar em seu virtualenv e executar este comando **na raiz do seu projeto**:: py.test -* To run the tests with coverage issue the command:: +* Para executar os teste de cobertura use:: py.test --cov . --cov-report term --cov-report html && firefox htmlcov/index.html -* The first time you run the tests after a migration (``./manage.py migrate``) use the db recreation option. - This needs to be done only once:: +* Na primeira vez que for executar os testes após uma migração (``./manage.py migrate``) use a opção de recriação da base de testes. + É necessário fazer usar esta opção apenas uma vez:: py.test --create-db Issues ------ -* Open all issues about the current development version (3.1) at the - `Github Issue Tracker `_. +* Abra todas as questões sobre o desenvolvimento atual no `Github Issue Tracker `_. -* You can file issues in either Portuguese or English (at least for the time being). +* Você pode escrever suas ``issues`` em Português ou Inglês (ao menos por enquanto).