Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adiciona docs de contribuição #151

Merged
merged 3 commits into from
May 20, 2024
Merged

Adiciona docs de contribuição #151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ddf5376
Adiciona docs de contribuição
giggio May 20, 2024
e9b2c85
Update CONTRIBUTING.md
giggio May 20, 2024
732c29f
Update CONTRIBUTING.md
giggio May 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 193 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
giggio marked this conversation as resolved.
Show resolved Hide resolved

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.
giggio marked this conversation as resolved.
Show resolved Hide resolved

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 assim esforços. Somente faça isso se a correção for bem rápida e pontual 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.
giggio marked this conversation as resolved.
Show resolved Hide resolved

## 🚀 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 `<seuusuario>` na url abaixo pelo seu usuário):

```bash
git clone https://github.com/<seuusuario>/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 <http://localhost:4000>. Você poderá acessar o Swagger em <http://localhost:4000/api>.

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 `<seubranch>` pelo nome do seu branch):

```bash
git checkout <seubranch>
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
```
173 changes: 14 additions & 159 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 `<seuusuario>` na url abaixo pelo seu usuário):

```bash
git clone https://github.com/<seuusuario>/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 <http://localhost:4000>. Você poderá acessar o Swagger em <http://localhost:4000/api>.

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 `<seubranch>` pelo nome do seu branch):

```bash
git checkout <seubranch>
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).
Loading