From ddf537620ad08b88d2c62cc8c7c2952abb862c84 Mon Sep 17 00:00:00 2001 From: Giovanni Bassi Date: Sun, 19 May 2024 21:33:51 -0300 Subject: [PATCH] =?UTF-8?q?Adiciona=20docs=20de=20contribui=C3=A7=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 173 ++++------------------------------------- docs/endpoints.md | 29 +++++++ 3 files changed, 236 insertions(+), 159 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/endpoints.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..6ee0ffcb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,193 @@ +# Contribuindo + +Você pode contribuir com o projeto de diversas formas, implementando uma +funcionalidade nova, corrigindo um bug, procurando bugs, revisando pull +requests, entre outras. +Para se inteirar do projeto, entre no +[Discord](https://discord.gg/vjZS6BQXvM) e participe das discussões. + +## 🤝 Contribuindo com atividades que não são de código + +O projeto precisa de ajuda em diversas frentes diferentes, como QA, produto, +design e gestão. Entre no servidor do Discord, onde há canais específicos para +essas atividades. + +Se você encontrou um bug, vá nas +[issues](https://github.com/SOS-RS/backend/issues) +do projeto e reporte-o lá. Verifique antes se já não existe um bug aberto para o +problema que quer relatar, usando a busca. O mesmo vale para novas +funcionalidades. + +O restante deste documento focará nas contribuições de código. + +## ✅ Escolhendo qual será sua contribuição de código + +Verifique no [projeto do Github](https://github.com/orgs/SOS-RS/projects/1) +quais funcionalidades ainda não foram implementadas e já estão prontas para +serem desenvolvidas, elas estarão na coluna "Disponível pra dev". Lá há itens de +backend e frontend, então atente-se para qual você gostaria de participar. + +Após escolher o item que quer trabalhar, faça um comentário no issue informando +que quer contribuir para sua entrega. Uma pessoa que administra o repositório +marcará você como a pessoa responsável por aquele issue, e marcará o item como +"Em desenvolvimento". + +A partir daí você já pode trabalhar no item que escolheu. + +Você também pode mandar a contribuição diretamente, sem avisar, mas corre o +risco de alguém solicitar para trabalhar no item e entregá-lo junto ou antes de +você, desperdiçando esforços. Faça isso só se a correção for bem rápida, para +evitar o desperdício. + +⚠️ **Importante**: Itens de alta prioridade precisam ser entregues o mais rápido possível, +idealmente em até dois dias. Verifique se tem tempo livre suficiente para se +dedicar a um item de urgência, a fim de evitar segurar o item por tempo demais +de forma desnecessária. + +## 🚀 Configuração Inicial Local + +1. Faça um fork do repositório para o seu usuário (uma boa ideia é usar um nome mais descritivo do que `backend`, como `sos-rs-backend`). +2. Clone o repositório (troque `` na url abaixo pelo seu usuário): + + ```bash + git clone https://github.com//sos-rs-backend.git + ``` + +3. Faça uma cópia do arquivo `.env`, e altere `DB_HOST=sos-rs-db` para `DB_HOST=localhost`: + + ```bash + sed 's/sos-rs-db/localhost/g' .env.local > .env + # ou copie o arquivo e altere no seu editor preferido + ``` + +4. Inicie o banco de dados com o Docker (adicione `-d` para rodar em background): + + ```bash + docker compose -f docker-compose.dev.yml up db + # ou em background: + docker compose -f docker-compose.dev.yml up db -d + # para ver os logs: + docker logs sos-rs-db + ``` + +5. Instale as dependências: + + ```bash + npm install + npx prisma generate + npx prisma migrate dev + ``` + +6. Inicie o servidor: + + ```bash + npm start + # ou com watch: + npm run start:dev + ``` + + A API estará disponível em . Você poderá acessar o Swagger em . + +7. Rode os testes: + + ```bash + npm test + # ou com watch: + npm run test:watch + ``` + +## 💻 Codificando e enviando + +1. Faça suas alterações. Não deixe de criar os testes. +2. Rode os testes com `npm test`, feitos com [Jest](https://jestjs.io/). +3. Rode o lint com `npm run lint`. +4. Crie um branch com o git `git checkout -b nomedobranch`. +5. Faça um commit com `git commit`. +6. Faça um push para o seu repositório com `git push`. +7. [Sincronize seu repositório](#-sincronizando). +8. [Abra um pull request](https://docs.github.com/pt/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). + Não deixe de informar, no seu pull request, qual a issue que está fechando. + Idealmente coloque um comentário no PR que já fechará a issue, como + `fixes #xxxx` ou `closes #xxxx` (onde `xxxx` é o número do issue). Veja + [como isso funciona](https://docs.github.com/pt/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests). +9. Acompanhe a revisão do PR. Algumas verificações automáticas serão feitas (o + Github Actions rodará os testes, por exemplo). Se uma delas falhar, corrija-a, a + revisão humana só começa quando estas checagem estão passando. Após abrir o + PR uma pessoa que administra o projeto pode pedir revisões e alterações. + Busque respondê-las o mais rápido possível para que o PR possa ser integrado. + +## 🔄 Sincronizando + +Você vai precisar, de tempos em tempos, sincronizar a branch `develop` do +seu repositório. Você pode usar o botão `Sync fork` do Github +(veja [os docs](https://docs.github.com/pt/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)). +Ou você pode fazer manualmente, o que te permite fazer a sincronização sem depender do Github: + +1. Antes de mais nada, se estiver no meio de uma contribuição, verifique que já commitou + tudo que tinha pra commitar, e então faça checkout do branch `develop`: + + ```bash + git checkout develop + ``` + +2. Adicione o repositório oficial como remoto com nome `upstream` (só necessário na primeira vez): + + ```bash + git remote add upstream https://github.com/SOS-RS/backend.git + ``` + +3. Faça pull do branch `develop`: + + ```bash + git pull upstream develop + ``` + +4. Se estiver no meio de uma contribuição, faça um rebase no branch `develop` + (substitua `` pelo nome do seu branch): + + ```bash + git checkout + git rebase develop + ``` + + Após o rebase, é importante rodar novamente a aplicação e verificar se tudo + continua funcionando, inclusive os testes. + +## 🗂 Dump do Banco de Dados + +Para iniciar com dados de exemplo, utilize o dump do banco disponível em `prisma/dev_dump.sql`. Este arquivo +pode ser executado após as migrations estarem aplicadas. + +Se estiver usando Docker, os comandos para carregar o dump são: + +```bash +# Copiar o dump para a pasta temporária do Docker +docker cp prisma/dev_dump.sql sos-rs-db:/tmp/dump.sql +# Importar o dump para o banco +docker exec -i sos-rs-db psql -U root -d sos_rs -f /tmp/dump.sql +``` + +## 🐳 Configuração com Docker + +Para desenvolvedores de frontend que não precisam executar localmente a API e o banco, siga estes passos: + +1. Clone o arquivo `.env` de exemplo: + + ```bash + cp .env.local .env + ``` + + Se você não fizer este passo você precisa adicionar as portas no + `docker-compose.dev.yml` para permitir acessos externos: + + ```yaml + ports: + - '5432:5432' + - '4000:4000' + ``` + +2. Use o seguinte comando para criar e iniciar o banco via Docker: + + ```bash + docker-compose -f docker-compose.dev.yml up + ``` diff --git a/README.md b/README.md index 020edaa5..65afc611 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,13 @@ autenticação de usuários, gerenciamento de abrigos e suprimentos, e muito mai Se você quiser discutir ideias, problemas ou contribuições, sinta-se à vontade para se juntar ao nosso servidor do Discord [aqui](https://discord.gg/vjZS6BQXvM). +## 🤝 Contribuição + +Contribuições são muito bem-vindas! Se deseja ajudar, veja o +[documento de contribuição](./CONTRIBUTING.md). + +Sua ajuda é crucial para apoiar a comunidade afetada pelas enchentes no Rio Grande do Sul! + ## 🛠 Tecnologias Utilizadas - **🟢 Node.js**: Ambiente de execução para JavaScript. @@ -15,168 +22,16 @@ Discord [aqui](https://discord.gg/vjZS6BQXvM). - **🐦 Nest**: Framework de alto desempenho para aplicações web em Node.js. - **📦 PostgreSQL**: Banco de dados relacional robusto e eficiente. -## 🗂 Dump do Banco de Dados - -Para iniciar com dados de exemplo, utilize o dump do banco disponível em `prisma/dev_dump.sql`. Este arquivo -pode ser executado após as migrations estarem aplicadas. - -Se estiver usando Docker, os comandos para carregar o dump são: - -```bash -# Copiar o dump para a pasta temporária do Docker -docker cp prisma/dev_dump.sql sos-rs-db:/tmp/dump.sql - -# Importar o dump para o banco -docker exec -i sos-rs-db psql -U root -d sos_rs -f /tmp/dump.sql -``` - -## 🐳 Configuração com Docker - -Para desenvolvedores de frontend que não precisam executar localmente a API e o banco, siga estes passos: - -1. Clone o arquivo `.env` de exemplo: - - ```bash - cp .env.local .env - ``` - -2. Use o seguinte comando para criar e iniciar o banco via Docker: - - ```bash - docker-compose -f docker-compose.dev.yml up - ``` - -## 🚀 Configuração Inicial Local - -1. Faça um fork do repositório para o seu usuário (uma boa ideia é usar um nome mais descritivo do que `backend`, como `sos-rs-backend`). -2. Clone o repositório (troque `` na url abaixo pelo seu usuário): - - ```bash - git clone https://github.com//sos-rs-backend.git - ``` - -3. Faça uma cópia do arquivo `.env`, e altere `DB_HOST=sos-rs-db` para `DB_HOST=localhost`: - - ```bash - sed 's/sos-rs-db/localhost/g' .env.local > .env - # ou copie o arquivo e altere no seu editor preferido - ``` - -4. Inicie o banco de dados com o Docker (adicione `-d` para rodar em background): - - ```bash - docker compose -f docker-compose.dev.yml up db - # ou em background: - docker compose -f docker-compose.dev.yml up db -d - # para ver os logs: - docker logs sos-rs-db - ``` - -5. Instale as dependências: - - ```bash - npm install - npx prisma generate - npx prisma migrate dev - ``` - -6. Inicie o servidor: - - ```bash - npm start - # ou com watch: - npm run start:dev - ``` - - A API estará disponível em . Você poderá acessar o Swagger em . - -7. Rode os testes: - - ```bash - npm test - # ou com watch: - npm run test:watch - ``` - -### Contribuindo - -1. Faça suas alterações; -2. Rode os testes com `npm test`; -3. Rode o lint com `npm run lint`; -4. Crie um branch com o git `git checkout -b nomedobranch`; -5. Faça um commit com `git commit`; -6. Faça um push para o seu repositório com `git push`; -7. [Sincronize seu repositório](#sincronizando); -8. Abra um pull request. - -## Sincronizando - -Você vai precisar, de tempos em tempos, sincronizar a branch `develop` do -seu repositório. Você pode usar o botão `Sync fork` do Github -(veja [os docs](https://docs.github.com/pt/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)). -Ou você pode fazer manualmente, o que te permite fazer a sincronização sem depender do Github: - -1. Antes de mais nada, se estiver no meio de uma contribuição, verifique que já commitou - tudo que tinha pra commitar, e então faça checkout do branch `develop`: - - ```bash - git checkout develop - ``` - -2. Adicione o repositório oficial como remoto com nome `upstream` (só necessário na primeira vez): - - ```bash - git remote add upstream https://github.com/SOS-RS/backend.git - ``` - -3. Faça pull do branch `develop`: - - ```bash - git pull upstream develop - ``` - -4. Se estiver no meio de uma contribuição, faça um rebase no branch `develop` - (substitua `` pelo nome do seu branch): - - ```bash - git checkout - git rebase develop - ``` - - ## 📡 API Endpoints -### 🧑‍💻 Usuários - -- **📝 POST /users** - Registra um novo usuário. -- **🔧 PUT /users** - Atualiza um usuário existente. - -### 🚪 Sessões - -- **📝 POST /sessions** - Inicia uma nova sessão de usuário. -- **👀 GET /sessions/:sessionId** - Retorna detalhes de uma sessão. -- **🔧 PUT /sessions/:sessionId** - Atualiza uma sessão. - -### 🏠 Abrigos +Veja o documento de [endpoints](./docs/endpoints.md). -- **📝 POST /shelters** - Registra um novo abrigo. -- **🔧 PUT /shelters/:shelterId** - Atualiza um abrigo. -- **👀 GET /shelters** - Lista abrigos. +## Licença -### 📦 Suprimentos +Este código está licenciado usando a +[licença MIT](./LICENSE). -- **📝 POST /supply** - Registra um novo item de suprimento. -- **🔧 PUT /supplies/:supplyId** - Atualiza um suprimento. -- **👀 GET /supplies** - Lista suprimentos. +## Contribuidores -### 🏷️ Categorias de Suprimentos - -- **📝 POST /supply-categories** - Registra uma nova categoria de suprimentos. -- **🔧 PUT /supply-categories/:categoryId** - Atualiza uma categoria. - -## 🤝 Contribuição - -Contribuições são muito bem-vindas! Se deseja ajudar, faça um fork do repositório, crie uma branch com suas -modificações, e envie um pull request. - -Sua ajuda é crucial para apoiar a comunidade afetada pelas enchentes no Rio Grande do Sul! +Os contribuidores são voluntários, e podem ser encontrados +[na página de contribuidores](https://github.com/SOS-RS/backend/graphs/contributors). diff --git a/docs/endpoints.md b/docs/endpoints.md new file mode 100644 index 00000000..d0d51129 --- /dev/null +++ b/docs/endpoints.md @@ -0,0 +1,29 @@ +# 📡 API Endpoints + +## 🧑‍💻 Usuários + +- **📝 POST /users** - Registra um novo usuário. +- **🔧 PUT /users** - Atualiza um usuário existente. + +## 🚪 Sessões + +- **📝 POST /sessions** - Inicia uma nova sessão de usuário. +- **👀 GET /sessions/:sessionId** - Retorna detalhes de uma sessão. +- **🔧 PUT /sessions/:sessionId** - Atualiza uma sessão. + +## 🏠 Abrigos + +- **📝 POST /shelters** - Registra um novo abrigo. +- **🔧 PUT /shelters/:shelterId** - Atualiza um abrigo. +- **👀 GET /shelters** - Lista abrigos. + +## 📦 Suprimentos + +- **📝 POST /supply** - Registra um novo item de suprimento. +- **🔧 PUT /supplies/:supplyId** - Atualiza um suprimento. +- **👀 GET /supplies** - Lista suprimentos. + +## 🏷️ Categorias de Suprimentos + +- **📝 POST /supply-categories** - Registra uma nova categoria de suprimentos. +- **🔧 PUT /supply-categories/:categoryId** - Atualiza uma categoria.