This is the documentation for the current development code. Choose a version from the menu to see documentation for released versions since v0.7.5.

Developer Environment

Pré-requisitos

Estas instruções supoem que você esteja rodando a BookWyrm utilizando o Docker. Você vai precisar instalar o Docker e o docker-compose para começar.

If you are contributing to BookWyrm in a dockerless development environment we would love for you to help us update this guide to include instructions for setting up a dockerless development environment.

Configurando o ambiente de desenvolvimento

Get the code

  1. Faça uma cópia do código da BookWyrm no GitHub. Você pode criar uma bifurcação (fork) do repositório e então usar git clone pra baixar o código para seu computador.
  2. Vá ao diretório onde o código foi baixado no seu computador; você trabalhará a partir dele daqui em diante.
  3. Development occurs on the main branch, so ensure that is the branch you have checked out: git checkout main
  4. Set up your development environment variables file by copying the example environment files (.env.example and .env.dev.example) into new files named .env and env.dev. Na linha de comando, você pode fazer assim:
cp .env.example .env
cp .env.dev.example .env.dev

Most environment variables are set in the .env file, used in production, but for some development workflows that is overridden by the env.dev file. When developing for BookWyrm, you will need both files.

Build and run

  1. In the command line, run:
./bw-dev create_secrets # Create the secrets file with random values. You only need to do this once.
./bw-dev dev up --build # Build and start development stack
./bw-dev dev runweb python manage.py admin_code # Shows the admin-code for initial setup. You only need to do this once.
  1. Once the build is complete, you can access the instance at http://localhost:1333. If you have removed the PORT value in .env.dev this will be http://localhost. If you have changed the port, swap out 1333 for the port you are using.
  2. You can now enter your admin key and create an admin user. From here everything is the same as described in "Running BookWyrm".

Se estiver curiosa: o comando ./bw-dev é um shell script simples que executa várias ferramentas: no exemplo acima, você poderia pular o script e executar docker-compose build ou docker-compose up diretamente, se preferir. ./bw-dev só junta esses comandos em um só, por conveniência. Run it without arguments to get a list of available commands, read the documentation page for it, or open it up and look around to see exactly what each command is doing!

Editando e criando Modelos (Models)

Se você quiser editar ou criar um modelo, você provavelmente vai alterar a estrutura do banco de dados. Para que essas alterações funcionem, você precisará executar o comando makemigrations do Django para criar um novo arquivo de migrações do Django e então migrá-lo:

./bw-dev makemigrations
./bw-dev dev migrate

Editando arquivos estáticos

Toda vez que você alterar o CSS ou o JavaScript, você precisará rodar o comando collectstaticdo Django para que as alterações passem a funcionar:

./bw-dev dev collectstatic

Se você tiver o yarn instalado, você pode executar yarn watch:static para executar automaticamente o script toda vez que houver alguma mudança no diretório bookwyrm/static.

Run code-linters and formatters

Before submitting patch, you should check ruff and other formatting tools. For those to work nicely, you should make sure you have development web-container and dev-tools build.

./bw-dev dev build # This is needed only once, if you haven't run dev stack previously
./bw-dev dev build dev-tools # This is needed only once and if you change pyproject.toml or Dockerfile

After those commands, you can run formatters and pytest and mypy with bw-dev command:

./bw-dev formatters
./bw-dev mypy
./bw-dev pytest

Run development code behind ngrok or other tunneling/proxy service

In .env.dev:

  1. If you use a tunneling/proxy service like ngrok, set DOMAIN to to the domain name you are using (e.g. abcd-1234.ngrok-free.app).
  2. If you need to use a particular port other than 1333, change PORT to wanted port (e.g. PORT=1333).

Check that you have all the required settings configured before proceeding.

If you try to register your admin account and see a message that CSRF verification failed you may have set your domain or port incorrectly.

Email (optional)

If you want to test sending emails, you will need to set up appropriate real values in the "Email config" section. You do not need to change anything for the separate EMAIL setting. These settings are in .env -file