This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contribuindo com o Site e Documentação do Selenium

Informações em como melhorar a documentação e exemplos de código para Selenium.

Selenium é um grande projeto de software, seu site e documentação são fundamentais para entender como as coisas funcionam e aprender maneiras eficazes de explorar seu potencial.

Este projeto contém o site e a documentação do Selenium. Isto é um esforço contínuo (não direcionado a nenhuma versão específica) para fornecer informações atualizadas sobre como usar o Selenium de forma eficaz, como se envolver e como contribuir para o Selenium.

As contribuições para o site e documentação seguem o processo descrito na seção abaixo sobre contribuições.

O projeto Selenium recebe contribuições de todos. Há um várias maneiras de ajudar:

Reportar um problema

Ao relatar um novo problema ou comentar sobre problemas existentes, por favor certifique-se de que as discussões estão relacionadas a questões técnicas concretas sobre o software Selenium, seu site e/ou documentação.

Todos os componentes do Selenium mudam bastante rápido ao longo do tempo, então este pode fazer com que a documentação fique desatualizada. Se você observar que este é o caso, como mencionado, não hesite em criar um problema para isso. Também pode ser possível que você saiba como atualizar a documentação, então, envie-nos um Pull Request com a alteração.

Se você não tem certeza se o que encontrou é um problema ou não, pergunte através dos canais de comunicação descritos em https://selenium.dev/support.

What to Help With

Creating Examples

Examples that need to be added are marked with:

Add Example

We want to be able to run all of our code examples in the CI to ensure that people can copy and paste and execute everything on the site. So we put the code where it belongs in the examples directory. Each page in the documentation correlates to a test file in each of the languages, and should follow naming conventions. For instance examples for this page https://www.selenium.dev/documentation/webdriver/browsers/chrome/ get added in these files:

  • "/examples/java/src/test/java/dev/selenium/browsers/ChromeTest.java"
  • "/examples/python/tests/browsers/test_chrome.py"
  • "/examples/dotnet/SeleniumDocs/Browsers/ChromeTest.cs"
  • "/examples/ruby/spec/browsers/chrome_spec.rb"
  • "/examples/javascript/test/browser/chromeSpecificCaps.spec.js"

Each example should get its own test. Ideally each test has an assertion that verifies the code works as intended. Once the code is copied to its own test in the proper file, it needs to be referenced in the markdown file.

For example, the tab in Ruby would look like this:

    {{< tab header="Ruby" >}}
    {{< gh-codeblock path="/examples/ruby/spec/browsers/chrome_spec.rb#L8-L9" >}}
    {{< /tab >}}

The line numbers at the end represent only the line or lines of code that actually represent the item being displayed. If a user wants more context, they can click the link to the GitHub page that will show the full context.

Make sure that if you add a test to the page that all the other line numbers in the markdown file are still correct. Adding a test at the top of a page means updating every single reference in the documentation that has a line number for that file.

Code examples may need a relevant website or web page to demonstrate the scenario. To ensure examples consistently work, it is recommended to use the test web pages available at https://www.selenium.dev/selenium/web/.

Finally, make sure that the tests pass in the CI.

Moving Examples

Examples that need to be moved are marked with:

Move Code

Everything from the Creating Examples section applies, with one addition.

Make sure the tab includes text=true. By default, the tabs get formatted for code, so to use markdown or other shortcode statements (like gh-codeblock) it needs to be declared as text. For most examples, the tabpane declares the text=true, but if some of the tabs have code examples, the tabpane cannot specify it, and it must be specified in the tabs that do not need automatic code formatting.

Contribuições

O projeto Selenium dá as boas-vindas a novos contribuidores. Indivíduos fazendo contribuições significativas e valiosas ao longo do tempo são transformados em Committers e recebem acesso de commit ao projeto.

Este guia irá guiá-lo através do processo de contribuição.

Passo 1: Fork

Faça um fork do projeto no GitHub e faça checkout na sua cópia localmente.

% git clone git@github.com:seleniumhq/seleniumhq.github.io.git
% cd seleniumhq.github.io

Dependências: Hugo

Usamos Hugo e Docsy theme para criar e gerar o website. Você vai necessitar de usar a versão “extended” Sass/SCSS do binário Hugo. Recomendamos a versão 0.167.0 .

Por favor siga as instruções do Docsy Install Hugo

Dependências: Go

O tema Docsy é obtido como um Hugo Module, então o Hugo precisa do Go para resolvê-lo ao executar hugo server. Instale qualquer versão que satisfaça o mínimo definido em go.mod.

Dependências: Node.js (opcional, para o pipeline de CSS de produção)

Node.js não é necessário para pré-visualizar o site com hugo server — no modo de desenvolvimento o Docsy ignora o PostCSS. Você só precisa do Node.js (qualquer versão atual) se quiser que o seu build local corresponda ao pipeline de CSS de produção (autoprefixer/PostCSS), executado por hugo --minify em build-site.sh. Nesse caso, execute npm install em website_and_docs primeiro.

Nota: Isso pode mudar em uma futura atualização do Hugo/Docsy. Se os assets do tema (por exemplo, Bootstrap/Font Awesome) migrarem do Hugo Modules para pacotes npm, npm install — e, portanto, o Node.js — pode se tornar necessário para todos os builds, não apenas para o pipeline de produção.

Passo 2: Branch

Crie uma branch e comece a hackear:

% git checkout -b my-feature-branch

Praticamos o desenvolvimento baseado em HEAD, o que significa que todas as mudanças são aplicadas diretamente no topo do dev.

Passo 3: Faça mudanças

O repositório contém o website e a documentação. Antes de começar a alterar coisas, por favor veja o resto dos passos para preparar as dependências e sub-módulos (veja os comandos abaixo).

Para fazer alterações ao website, trabalha na pasta website_and_docs. Para ver uma previsão do aspecto do website, execute hugo server a partir da raíz do projecto.

% git submodule update --init --recursive
% cd website_and_docs
% hugo server

See Style Guide for more information on our conventions for contribution

Passo 4: Commit

Primeiro, certifique-se de que o git saiba seu nome e endereço de e-mail:

% git config --global user.name 'Santa Claus'
% git config --global user.email 'santa@example.com'

Escrever boas mensagens de commit é importante. Uma mensagem de confirmação deve descrever o que mudou, por que e conter referência de problemas corrigidos (se houver). Siga estas diretrizes ao escrever um:

  1. A primeira linha deve ter cerca de 50 caracteres ou menos e conter uma breve da descrição da mudança.
  2. Mantenha a segunda linha em branco.
  3. Quebra todas as outras linhas em 72 colunas.
  4. Incluir Fixes # N, onde N é o número do problema que o commit corrige se houver.

Uma boa mensagem de confirmação pode ter a seguinte aparência:

explain commit normatively in one line

Body of commit message is a few lines of text, explaining things
in more detail, possibly giving some background about the issue
being fixed, etc.

The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
72 characters or so. That way `git log` will show things
nicely even when it is indented.

Fixes #141

A primeira linha deve ser significativa, pois é o que as pessoas veem quando executam git shortlog ou git log --oneline.

Passo 5: Rebase

Use git rebase (não git merge) para sincronizar seu trabalho de tempos em tempos.

% git fetch origin
% git rebase origin/trunk

Passo 6: Teste

Lembre-se sempre de executar o servidor local, com isso, você pode ter certeza de que suas alterações não prejudicaram nada.

Passo 7: Push

% git push origin my-feature-branch

Acesse https://github.com/yourusername/seleniumhq.github.io.git e clique em Pull Request e preencha o formulário. Por favor indique que você assinou o CLA. Para assinar o CLA, visite cla-assistant.io/SeleniumHQ/seleniumhq.github.io e clique no botão “Sign in with GitHub to agree” na página.

Os Pull Requests geralmente são revisados em alguns dias. Se houver comentários a abordar, aplique suas alterações em novos commits (de preferência fixups) e envie para a mesma branch.

Passo 8: Integração

Quando a revisão do código for concluída, um committer integrará seu PR no branch de tronco do repositório. Porque gostamos de manter um histórico linear no trunk, nós normalmente iremos dar Squash & Rebase no histórico da sua branch.

Comunicação

Todos os detalhes sobre como se comunicar com os colaboradores do projeto e a comunidade em geral podem ser encontrados em https://selenium.dev/support

1 - Contributing to the Selenium site

How to update the Selenium site pages outside of the documentation

The Selenium site is built with Hugo and the Docsy theme. The site root is the website_and_docs directory. Follow the contribution mechanics to set up your environment and preview your changes with hugo server.

Where things live

WhatWhere
Home pagecontent/_index.<language>.html
Top level pages (downloads, support, projects, sponsors, etc.)content/<page>/_index.html
Blog postscontent/blog/<year>/<post>.md
Page templates (e.g., the downloads page)layouts/<section>/list.html
Shortcodeslayouts/shortcodes/
Partials (navbar, footer, announcement banner, etc.)layouts/partials/
Images and other static filesstatic/ (e.g., static/images/)
Stylesassets/scss/
Structured data (e.g., sponsors)data/
Site configuration and menushugo.toml

Some pages have most of their content in the template instead of the Markdown file. For example, the content of the Downloads page lives in layouts/downloads/list.html.

Blog posts

Add a new Markdown file under content/blog/<year>/. Copy the front matter of a recent post and update the title, linkTitle, date, tags, categories, author, and description. To use a custom image when the post is shared on social media, add it under static/images/blog/<year>/ and reference it in the images front matter key.

Translations

The home page and the documentation are translated. Most of the other site pages, including the blog, are only available in English. When you change text on a translated page, see Translations in the style guide.

Checking your changes

Site changes are not covered by tests, so preview every page you changed with hugo server. Every pull request gets a Netlify deploy preview; check it before asking for a review.

2 - Contributing to the Selenium documentation

How the Selenium documentation is organized and how to change it

The documentation lives in website_and_docs/content/documentation. Follow the contribution mechanics to set up your environment and preview your changes with hugo server.

Structure

Each directory is a section of the documentation, and its _index.<language>.md file is the section landing page. Each page has one file per language:

  • <page>.en.md
  • <page>.ja.md
  • <page>.pt-br.md
  • <page>.zh-cn.md

When you add a page, add a file for each language. If you are not translating the content, copy the English text into the other language files.

Each page starts with front matter like this:

---
title: "Sentence capitalization title that describes the page"
linkTitle: "Short Title"
weight: 4
description: >
  One sentence summary of the page.
---

weight defines the order of the page in the navigation. See Capitalization of titles for the title and linkTitle conventions.

Writing

  • Keep the prose language independent. Anything specific to a language binding goes inside code tabs.
  • Follow the style guide for line length, alerts, and code tabs.
  • Mark missing content with the alerts described in the style guide, so others know where help is needed.
  • Link to other documentation pages with the ref shortcode, e.g., [Waits]({{< ref "waits.md" >}}), so broken links fail the build.

Code in the documentation

Code shown in the documentation must come from runnable examples. See Code examples for how to create them and render them on a page.

Translations

See Translations in the style guide.

3 - Contributing code examples

How to create runnable code examples and render them in the documentation

We want to be able to run all of our code examples in the CI to ensure that people can copy, paste and execute everything on the site. So the code lives in the examples directory, and the documentation renders it from there.

Creating examples

Examples that need to be added are marked with:

Add Example

Each page in the documentation correlates to a test file in each of the languages, and should follow naming conventions. For instance examples for this page https://www.selenium.dev/documentation/webdriver/browsers/chrome/ get added in these files:

  • "/examples/java/src/test/java/dev/selenium/browsers/ChromeTest.java"
  • "/examples/python/tests/browsers/test_chrome.py"
  • "/examples/dotnet/SeleniumDocs/Browsers/ChromeTest.cs"
  • "/examples/ruby/spec/browsers/chrome_spec.rb"
  • "/examples/javascript/test/browser/chromeSpecificCaps.spec.js"
  • "/examples/kotlin/src/test/kotlin/dev/selenium/browsers/ChromeTest.kt"

Follow these guidelines when writing an example:

  • Each example gets its own test. This keeps the example focused and lets the documentation point to exactly the lines that matter.
  • Use the Selenium test pages. Examples need a web page to work against. Use the pages available at https://www.selenium.dev/selenium/web/ instead of third party sites, which can change or go offline and break the examples.
  • Assert the outcome. Each test should have an assertion that verifies the code works as intended, so that a broken example fails the CI.
  • Keep the shown code free of test noise. Write the test so that the lines shown in the documentation are only the Selenium code the reader needs. Assertions and test setup are not shown, unless the assertion is the clearest way to show the result of the command (e.g., the value returned by a getter).
  • Run the tests. Run the tests for each language you changed locally, and make sure they pass in the CI. Each language directory in the examples directory has a README with the instructions to run its tests.

Moving examples

Examples that need to be moved are marked with:

Move Code

These are code examples that are written directly in the Markdown file. Everything from Creating examples applies: move the code into a test, then render it with gh-codeblock as described below.

Rendering examples

Once the code is in its own test, it needs to be referenced in the Markdown file with the gh-codeblock shortcode. For example, the tab in Ruby would look like this:

    {{< tab header="Ruby" >}}
    {{< gh-codeblock path="/examples/ruby/spec/browsers/chrome_spec.rb#L8-L9" >}}
    {{< /tab >}}

See Reference GitHub Examples in the style guide for the complete tabpane syntax. Keep in mind the following:

  • Show only the relevant lines. The line numbers at the end of the path (#L8-L9) select the lines that are displayed. Use a single line (#L8) or a range of lines (#L8-L9). Readers can click “View Complete Code” or “View on GitHub” to see the full test.
  • One range per code block. A gh-codeblock displays one continuous range of lines. If the lines you want to show are not next to each other, reorganize the test so they are, or use one gh-codeblock for each range.
  • Use text=true. By default, the tabs get formatted for code, so to use markdown or other shortcode statements (like gh-codeblock) it needs to be declared as text. For most examples, the tabpane declares the text=true, but if some of the tabs have code examples, the tabpane cannot specify it, and it must be specified in the tabs that do not need automatic code formatting.
  • Do not indent the gh-codeblock line. An indented line is rendered as a Markdown code block instead of running the shortcode.
  • Keep line numbers up to date. When you add, remove or move lines in an example file, every gh-codeblock that points to that file below the change needs new line numbers. Search website_and_docs/content for the file path, and check all languages of the page.
  • Add the example to all translations. Update the gh-codeblock references in the .ja.md, .pt-br.md and .zh-cn.md files of the page too.