Skip to content

Commit effeb8e

Browse files
giggiomarcieltorres
giggio
and
marcieltorres
authored
Adiciona docs de contribuição (#151)
Co-authored-by: Marciel Torres <[email protected]>
1 parent b2bd24a commit effeb8e

File tree

3 files changed

+236
-159
lines changed

3 files changed

+236
-159
lines changed

‎CONTRIBUTING.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Contribuindo
2+
3+
Você pode contribuir com o projeto de diversas formas, implementando uma
4+
funcionalidade nova, corrigindo um bug, procurando bugs, revisando pull
5+
requests, entre outras.
6+
Para se inteirar do projeto, entre no
7+
[Discord](https://discord.gg/vjZS6BQXvM) e participe das discussões.
8+
9+
## 🤝 Contribuindo com atividades que não são de código
10+
11+
O projeto precisa de ajuda em diversas frentes diferentes como: QA, produto,
12+
design e gestão. Entre no servidor do Discord onde há canais específicos para
13+
essas atividades.
14+
15+
Se você encontrou um bug, vá nas
16+
[issues](https://github.com/SOS-RS/backend/issues)
17+
do projeto e reporte-o lá. Verifique antes se já não existe um bug aberto para o
18+
problema que quer relatar, usando a busca. O mesmo vale para novas
19+
funcionalidades.
20+
21+
O restante deste documento focará nas contribuições de código.
22+
23+
## ✅ Escolhendo qual será sua contribuição de código
24+
25+
Verifique no [projeto do Github](https://github.com/orgs/SOS-RS/projects/1)
26+
quais funcionalidades ainda não foram implementadas e já estão prontas para
27+
serem desenvolvidas, elas estarão na coluna "Disponível pra dev". Lá há itens de
28+
backend e frontend, então atente-se para qual você gostaria de participar.
29+
30+
Após escolher o item que quer trabalhar, faça um comentário no issue informando
31+
que quer contribuir para sua entrega. Uma pessoa que administra o repositório
32+
marcará você como a pessoa responsável por aquele issue, e marcará o item como
33+
"Em desenvolvimento".
34+
35+
A partir daí você já pode trabalhar no item que escolheu.
36+
37+
Você também pode mandar a contribuição diretamente sem avisar, mas corre o
38+
risco de alguém solicitar para trabalhar no item e entregá-lo junto ou antes de
39+
você, desperdiçando assim esforços. Somente faça isso se a correção for bem rápida e pontual para
40+
evitar o desperdício.
41+
42+
⚠️ **Importante**: Itens de alta prioridade precisam ser entregues o mais rápido possível,
43+
idealmente em até dois dias. Verifique se tem tempo livre suficiente para se
44+
dedicar a um item de urgência, a fim de evitar segurar o item por tempo demais
45+
de forma desnecessária.
46+
47+
## 🚀 Configuração Inicial Local
48+
49+
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`).
50+
2. Clone o repositório (troque `<seuusuario>` na url abaixo pelo seu usuário):
51+
52+
```bash
53+
git clone https://github.com/<seuusuario>/sos-rs-backend.git
54+
```
55+
56+
3. Faça uma cópia do arquivo `.env`, e altere `DB_HOST=sos-rs-db` para `DB_HOST=localhost`:
57+
58+
```bash
59+
sed 's/sos-rs-db/localhost/g' .env.local > .env
60+
# ou copie o arquivo e altere no seu editor preferido
61+
```
62+
63+
4. Inicie o banco de dados com o Docker (adicione `-d` para rodar em background):
64+
65+
```bash
66+
docker compose -f docker-compose.dev.yml up db
67+
# ou em background:
68+
docker compose -f docker-compose.dev.yml up db -d
69+
# para ver os logs:
70+
docker logs sos-rs-db
71+
```
72+
73+
5. Instale as dependências:
74+
75+
```bash
76+
npm install
77+
npx prisma generate
78+
npx prisma migrate dev
79+
```
80+
81+
6. Inicie o servidor:
82+
83+
```bash
84+
npm start
85+
# ou com watch:
86+
npm run start:dev
87+
```
88+
89+
A API estará disponível em <http://localhost:4000>. Você poderá acessar o Swagger em <http://localhost:4000/api>.
90+
91+
7. Rode os testes:
92+
93+
```bash
94+
npm test
95+
# ou com watch:
96+
npm run test:watch
97+
```
98+
99+
## 💻 Codificando e enviando
100+
101+
1. Faça suas alterações. Não deixe de criar os testes.
102+
2. Rode os testes com `npm test`, feitos com [Jest](https://jestjs.io/).
103+
3. Rode o lint com `npm run lint`.
104+
4. Crie um branch com o git `git checkout -b nomedobranch`.
105+
5. Faça um commit com `git commit`.
106+
6. Faça um push para o seu repositório com `git push`.
107+
7. [Sincronize seu repositório](#-sincronizando).
108+
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).
109+
Não deixe de informar, no seu pull request, qual a issue que está fechando.
110+
Idealmente coloque um comentário no PR que já fechará a issue, como
111+
`fixes #xxxx` ou `closes #xxxx` (onde `xxxx` é o número do issue). Veja
112+
[como isso funciona](https://docs.github.com/pt/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests).
113+
9. Acompanhe a revisão do PR. Algumas verificações automáticas serão feitas (o
114+
Github Actions rodará os testes, por exemplo). Se uma delas falhar, corrija-a, a
115+
revisão humana só começa quando estas checagem estão passando. Após abrir o
116+
PR uma pessoa que administra o projeto pode pedir revisões e alterações.
117+
Busque respondê-las o mais rápido possível para que o PR possa ser integrado.
118+
119+
## 🔄 Sincronizando
120+
121+
Você vai precisar, de tempos em tempos, sincronizar a branch `develop` do
122+
seu repositório. Você pode usar o botão `Sync fork` do Github
123+
(veja [os docs](https://docs.github.com/pt/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)).
124+
Ou você pode fazer manualmente, o que te permite fazer a sincronização sem depender do Github:
125+
126+
1. Antes de mais nada, se estiver no meio de uma contribuição, verifique que já commitou
127+
tudo que tinha pra commitar, e então faça checkout do branch `develop`:
128+
129+
```bash
130+
git checkout develop
131+
```
132+
133+
2. Adicione o repositório oficial como remoto com nome `upstream` (só necessário na primeira vez):
134+
135+
```bash
136+
git remote add upstream https://github.com/SOS-RS/backend.git
137+
```
138+
139+
3. Faça pull do branch `develop`:
140+
141+
```bash
142+
git pull upstream develop
143+
```
144+
145+
4. Se estiver no meio de uma contribuição, faça um rebase no branch `develop`
146+
(substitua `<seubranch>` pelo nome do seu branch):
147+
148+
```bash
149+
git checkout <seubranch>
150+
git rebase develop
151+
```
152+
153+
Após o rebase, é importante rodar novamente a aplicação e verificar se tudo
154+
continua funcionando, inclusive os testes.
155+
156+
## 🗂 Dump do Banco de Dados
157+
158+
Para iniciar com dados de exemplo, utilize o dump do banco disponível em `prisma/dev_dump.sql`. Este arquivo
159+
pode ser executado após as migrations estarem aplicadas.
160+
161+
Se estiver usando Docker, os comandos para carregar o dump são:
162+
163+
```bash
164+
# Copiar o dump para a pasta temporária do Docker
165+
docker cp prisma/dev_dump.sql sos-rs-db:/tmp/dump.sql
166+
# Importar o dump para o banco
167+
docker exec -i sos-rs-db psql -U root -d sos_rs -f /tmp/dump.sql
168+
```
169+
170+
## 🐳 Configuração com Docker
171+
172+
Para desenvolvedores de frontend que não precisam executar localmente a API e o banco, siga estes passos:
173+
174+
1. Clone o arquivo `.env` de exemplo:
175+
176+
```bash
177+
cp .env.local .env
178+
```
179+
180+
Se você não fizer este passo você precisa adicionar as portas no
181+
`docker-compose.dev.yml` para permitir acessos externos:
182+
183+
```yaml
184+
ports:
185+
- '5432:5432'
186+
- '4000:4000'
187+
```
188+
189+
2. Use o seguinte comando para criar e iniciar o banco via Docker:
190+
191+
```bash
192+
docker-compose -f docker-compose.dev.yml up
193+
```

‎README.md

+14-159
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ autenticação de usuários, gerenciamento de abrigos e suprimentos, e muito mai
77
Se você quiser discutir ideias, problemas ou contribuições, sinta-se à vontade para se juntar ao nosso servidor do
88
Discord [aqui](https://discord.gg/vjZS6BQXvM).
99

10+
## 🤝 Contribuição
11+
12+
Contribuições são muito bem-vindas! Se deseja ajudar, veja o
13+
[documento de contribuição](./CONTRIBUTING.md).
14+
15+
Sua ajuda é crucial para apoiar a comunidade afetada pelas enchentes no Rio Grande do Sul!
16+
1017
## 🛠 Tecnologias Utilizadas
1118

1219
- **🟢 Node.js**: Ambiente de execução para JavaScript.
@@ -15,168 +22,16 @@ Discord [aqui](https://discord.gg/vjZS6BQXvM).
1522
- **🐦 Nest**: Framework de alto desempenho para aplicações web em Node.js.
1623
- **📦 PostgreSQL**: Banco de dados relacional robusto e eficiente.
1724

18-
## 🗂 Dump do Banco de Dados
19-
20-
Para iniciar com dados de exemplo, utilize o dump do banco disponível em `prisma/dev_dump.sql`. Este arquivo
21-
pode ser executado após as migrations estarem aplicadas.
22-
23-
Se estiver usando Docker, os comandos para carregar o dump são:
24-
25-
```bash
26-
# Copiar o dump para a pasta temporária do Docker
27-
docker cp prisma/dev_dump.sql sos-rs-db:/tmp/dump.sql
28-
29-
# Importar o dump para o banco
30-
docker exec -i sos-rs-db psql -U root -d sos_rs -f /tmp/dump.sql
31-
```
32-
33-
## 🐳 Configuração com Docker
34-
35-
Para desenvolvedores de frontend que não precisam executar localmente a API e o banco, siga estes passos:
36-
37-
1. Clone o arquivo `.env` de exemplo:
38-
39-
```bash
40-
cp .env.local .env
41-
```
42-
43-
2. Use o seguinte comando para criar e iniciar o banco via Docker:
44-
45-
```bash
46-
docker-compose -f docker-compose.dev.yml up
47-
```
48-
49-
## 🚀 Configuração Inicial Local
50-
51-
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`).
52-
2. Clone o repositório (troque `<seuusuario>` na url abaixo pelo seu usuário):
53-
54-
```bash
55-
git clone https://github.com/<seuusuario>/sos-rs-backend.git
56-
```
57-
58-
3. Faça uma cópia do arquivo `.env`, e altere `DB_HOST=sos-rs-db` para `DB_HOST=localhost`:
59-
60-
```bash
61-
sed 's/sos-rs-db/localhost/g' .env.local > .env
62-
# ou copie o arquivo e altere no seu editor preferido
63-
```
64-
65-
4. Inicie o banco de dados com o Docker (adicione `-d` para rodar em background):
66-
67-
```bash
68-
docker compose -f docker-compose.dev.yml up db
69-
# ou em background:
70-
docker compose -f docker-compose.dev.yml up db -d
71-
# para ver os logs:
72-
docker logs sos-rs-db
73-
```
74-
75-
5. Instale as dependências:
76-
77-
```bash
78-
npm install
79-
npx prisma generate
80-
npx prisma migrate dev
81-
```
82-
83-
6. Inicie o servidor:
84-
85-
```bash
86-
npm start
87-
# ou com watch:
88-
npm run start:dev
89-
```
90-
91-
A API estará disponível em <http://localhost:4000>. Você poderá acessar o Swagger em <http://localhost:4000/api>.
92-
93-
7. Rode os testes:
94-
95-
```bash
96-
npm test
97-
# ou com watch:
98-
npm run test:watch
99-
```
100-
101-
### Contribuindo
102-
103-
1. Faça suas alterações;
104-
2. Rode os testes com `npm test`;
105-
3. Rode o lint com `npm run lint`;
106-
4. Crie um branch com o git `git checkout -b nomedobranch`;
107-
5. Faça um commit com `git commit`;
108-
6. Faça um push para o seu repositório com `git push`;
109-
7. [Sincronize seu repositório](#sincronizando);
110-
8. Abra um pull request.
111-
112-
## Sincronizando
113-
114-
Você vai precisar, de tempos em tempos, sincronizar a branch `develop` do
115-
seu repositório. Você pode usar o botão `Sync fork` do Github
116-
(veja [os docs](https://docs.github.com/pt/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)).
117-
Ou você pode fazer manualmente, o que te permite fazer a sincronização sem depender do Github:
118-
119-
1. Antes de mais nada, se estiver no meio de uma contribuição, verifique que já commitou
120-
tudo que tinha pra commitar, e então faça checkout do branch `develop`:
121-
122-
```bash
123-
git checkout develop
124-
```
125-
126-
2. Adicione o repositório oficial como remoto com nome `upstream` (só necessário na primeira vez):
127-
128-
```bash
129-
git remote add upstream https://github.com/SOS-RS/backend.git
130-
```
131-
132-
3. Faça pull do branch `develop`:
133-
134-
```bash
135-
git pull upstream develop
136-
```
137-
138-
4. Se estiver no meio de uma contribuição, faça um rebase no branch `develop`
139-
(substitua `<seubranch>` pelo nome do seu branch):
140-
141-
```bash
142-
git checkout <seubranch>
143-
git rebase develop
144-
```
145-
146-
14725
## 📡 API Endpoints
14826

149-
### 🧑‍💻 Usuários
150-
151-
- **📝 POST /users** - Registra um novo usuário.
152-
- **🔧 PUT /users** - Atualiza um usuário existente.
153-
154-
### 🚪 Sessões
155-
156-
- **📝 POST /sessions** - Inicia uma nova sessão de usuário.
157-
- **👀 GET /sessions/:sessionId** - Retorna detalhes de uma sessão.
158-
- **🔧 PUT /sessions/:sessionId** - Atualiza uma sessão.
159-
160-
### 🏠 Abrigos
27+
Veja o documento de [endpoints](./docs/endpoints.md).
16128

162-
- **📝 POST /shelters** - Registra um novo abrigo.
163-
- **🔧 PUT /shelters/:shelterId** - Atualiza um abrigo.
164-
- **👀 GET /shelters** - Lista abrigos.
29+
## Licença
16530

166-
### 📦 Suprimentos
31+
Este código está licenciado usando a
32+
[licença MIT](./LICENSE).
16733

168-
- **📝 POST /supply** - Registra um novo item de suprimento.
169-
- **🔧 PUT /supplies/:supplyId** - Atualiza um suprimento.
170-
- **👀 GET /supplies** - Lista suprimentos.
34+
## Contribuidores
17135

172-
### 🏷️ Categorias de Suprimentos
173-
174-
- **📝 POST /supply-categories** - Registra uma nova categoria de suprimentos.
175-
- **🔧 PUT /supply-categories/:categoryId** - Atualiza uma categoria.
176-
177-
## 🤝 Contribuição
178-
179-
Contribuições são muito bem-vindas! Se deseja ajudar, faça um fork do repositório, crie uma branch com suas
180-
modificações, e envie um pull request.
181-
182-
Sua ajuda é crucial para apoiar a comunidade afetada pelas enchentes no Rio Grande do Sul!
36+
Os contribuidores são voluntários, e podem ser encontrados
37+
[na página de contribuidores](https://github.com/SOS-RS/backend/graphs/contributors).

0 commit comments

Comments
 (0)