Configuração de desenvolvimento e comandos para compilar, servir e mais

Configuração de IDE de nuvem

Gitpod

Para trabalhar via Gitpod.io:

1. Faça um fork deste repositório. Para ajuda, veja Fazer fork de um repositório.

2. De gitpod.io/workspaces, crie um novo workspace (faça isso apenas uma vez) ou abra um workspace existente sobre seu fork. Você também pode visitar um link da forma: https://gitpod.io#https://github.com/SEU_ID_GITHUB/opentelemetry.io.

   Nota: Se você tem as permissões necessárias para trabalhar neste repositório, ou apenas quer dar uma olhada, abra https://gitpod.io/#https://github.com/open-telemetry/opentelemetry.io.

O Gitpod instala automaticamente os pacotes específicos do repositório para você. Agora você está pronto para compilar, servir e fazer atualizações nos arquivos do site. Para mais detalhes sobre como submeter alterações, veja Enviando conteúdo.

Codespaces

Para trabalhar via GitHub Codespaces:

1. Faça um fork do repositório do site.
2. Abra um Codespace a partir do seu fork.

Seu ambiente de desenvolvimento será inicializado via a configuração DevContainer. Agora você está pronto para compilar, servir e fazer atualizações nos arquivos do site. Para mais detalhes sobre como submeter alterações, veja Enviando conteúdo.

Configuração local

1. Faça um fork e então clone o repositório do site em https://github.com/open-telemetry/opentelemetry.io.

2. Vá para o diretório do repositório:

   cd opentelemetry.io
   

3. Instale a versão do Node.js fixada no arquivo .nvmrc (uma versão LTS ativa). Recomendamos o nvm para gerenciar a instalação do Node; no Linux, execute:

   nvm install
   

   Para instalar no Windows, use o nvm-windows, que não lê o arquivo .nvmrc por conta própria; o comando a seguir fornece a versão fixada. Recomendamos usar cmd e não o Windows PowerShell:

   for /f %v in (.nvmrc) do nvm install %v && nvm use %v
   

4. Obtenha os pacotes npm e outros pré-requisitos, usando a configuração com versões exatas do lockfile e sem execução de scripts que o devcontainer utiliza:

   npm run install:safe
   

   Ou, use uma instalação padrão:

   npm install
   

   Ambas as instalações usam as versões de dependências fixadas no package-lock.json versionado, e qualquer script de ciclo de vida de dependência que for executado está sujeito à lista de permissões revisada. Relacionado: atualização de dependências.

Abra sua IDE favorita. Agora você está pronto para compilar, servir e fazer atualizações nos arquivos do site. Para mais detalhes sobre como submeter alterações, veja Enviando conteúdo.

Compilar

Para compilar o site execute:

npm run build

Os arquivos gerados do site estão em public.

ERROR error building site: ...[long message]... TOCSS: failed to transform "/scss/main.scss" (text/x-scss)

ERROR failed to load modules: module "github.com/FortAwesome/Font-Awesome" not found

npm install

Servir

Para servir o site execute:

npm run serve

O site é servido em localhost:1313.

O comando serve disponibiliza arquivos da memória, não do disco.

Para testar redirecionamentos do Netlify, use a prévia de deploy do seu PR.

Caso ocorra um erro como too many open files ou pipe failed no macOS, pode ser necessário aumentar o limite de descritores de arquivo. Veja Hugo issue #6109.

Conteúdo e submódulos

O site é construído a partir do seguinte conteúdo:

• Arquivos sob content/, static/, etc. conforme os padrões do Hugo.
• Pontos de montagem, definidos pela configuração do Hugo em config/_default/module-template.yaml. As montagens são diretamente de submódulos git sob content-modules, ou conteúdo pré-processado de content-modules (colocado sob tmp/), e em nenhum outro lugar.

Alterações em submódulos

Se você alterar qualquer conteúdo dentro de um submódulo content-modules, então você precisa primeiro submeter um PR (contendo as alterações do submódulo) para o repositório do submódulo. Somente depois que o PR do submódulo for aceito, você pode atualizar o submódulo e ter as mudanças publicadas neste site.

É mais fácil gerenciar suas alterações em content-modules trabalhando com o repositório ao qual o submódulo correspondente está vinculado, em vez de dentro do próprio submódulo.

Contribuidores experientes podem trabalhar diretamente no submódulo. Você então consegue construir e disponibilizar diretamente suas alterações (do submódulo). Por padrão, os scripts de CI obtêm submódulos a cada invocação. Para prevenir esse comportamento enquanto você trabalha dentro de um submódulo, defina a variável de ambiente GET=no. Você também precisa executar git fetch --unshallow no submódulo antes de poder submeter um PR. De maneira alternativa, defina DEPTH=100 e busque novamente os submódulos.

Suporte a DevContainer

Este repositório está configurado para uso em Development Containers, que são suportados por várias IDEs de nuvem e locais como (em ordem alfabética):

• Codespaces
• DevPod
• Gitpod
• VSCode

Ferramentas

Code-excerpter

Use o code-excerpter para trechos de código que devem permanecer sincronizados com arquivos-fonte deste repositório. Páginas do site em qualquer idioma podem conter trechos de código, mas o conteúdo original que os utiliza é escrito em inglês em content/en e depois atualizado pelas equipes de localização para seus próprios idiomas.

Na página de origem em inglês, coloque uma diretiva de trecho de arquivo imediatamente antes do bloco de código delimitado que ela atualiza:

<?code-excerpt path-base="content-modules/opentelemetry-java-examples/doc-snippets/getting-started"?>

<?code-excerpt "src/main/java/otel/DiceApplication.java" from="@SpringBootApplication"?>

```java
@SpringBootApplication
public class DiceApplication {
  public static void main(String[] args) {
    SpringApplication app = new SpringApplication(DiceApplication.class);
    app.setBannerMode(Banner.Mode.OFF);
    app.run(args);
  }
}
```

Use uma diretiva opcional path-base uma única vez, próximo ao topo da página, quando vários trechos vierem do mesmo diretório. Para detalhes sobre a sintaxe da diretiva code-excerpt, consulte o README do code-excerpter.

Edite o arquivo-fonte ou a diretiva, não o bloco de código. Em seguida, execute o seguinte script npm:

npm run fix:code-excerpts

Para verificar se os trechos de código estão atualizados, execute:

npm run check:code-excerpts