Sistema de controle de versão para documentação do SQL

  • Artigo

Aplica-se a:SQL ServerBanco de Dados SQL do AzureAzure Synapse AnalyticsPDW (Analytics Platform System)

Este artigo explica sobre nosso sistema de controle de versão para documentação do SQL. O sistema de controle de versão sabe sobre produtos e suas versões. Ele permite que você escolha o produto e a versão de seu interesse. Em seguida, ele exibe a documentação apropriada.

Aplica-se a produtos

A maioria dos artigos do SQL Server tem as palavras Aplica-se a sob o título. Na mesma linha, segue uma lista prática de produtos SQL com indicadores de se o artigo é relevante para o produto. Por exemplo, o produto SQL Server pode ser indicado como relevante, enquanto o Banco de Dados SQL do Azure pode ser indicado como irrelevante para o artigo.

A linha Aplica-se a não trata das versões dos produtos. Um esforço é feito para evitar discrepâncias entre a linha Aplica-se a e o aspecto dos produtos das configurações do sistema de controle de versão.

Histórico de conjuntos de arquivos separados

Para o SQL Server 2014 e versões anteriores, cada versão tem sua própria cópia completa separada dos arquivos de documentação. Por exemplo, a documentação do SQL Server 2014 começou como uma cópia da documentação do SQL Server 2012. A cópia do 2014 foi editada durante o ciclo de desenvolvimento do produto.

Essa abordagem antiga significava que se uma falha fosse descoberta na documentação do 2014, a falha também poderia existir em 2012 e 2008. Isso tornava mais difícil a correção de falhas e manutenção geral.

Várias versões nos mesmos arquivos

Por esse motivo e por outros, os arquivos de documentação do SQL Server 2016 também são para o 2017, o 2019 e provavelmente para o <vNext>. Essa consolidação se tornou prática porque agora atribuímos monikers de controle de versão aos nossos arquivos de documentação do SQL Server. Os monikers de controle de versão são atribuídos ou inseridos explicitamente a qualquer grau de granularidade que faça sentido para cada arquivo de documentação fornecido.

Controle de versão na interface do usuário

Quando você exibe qualquer artigo de documentação do SQL usando nosso site Docs, o moniker de controle de versão escolhido no momento fica visível acima do sumário. O controle é uma lista suspensa.

media_versioning-control-10-sql-server-2017.png

Se você quiser ver a documentação de uma versão diferente do SQL Server, clique na seta de expansão localizada no final do moniker do controle de versão atual. Em seguida, clique para escolher qualquer combinação de produto e versão desejada. Quando você clica em uma versão diferente, a documentação exibida muda repentinamente para mostrar as diferenças para a versão recém-escolhida. Pode ou não haver alterações e ambos os casos são comuns.

media_versioning-control-20-expanded.png

Parâmetro HTTPS view=

Cada artigo cujo endereço web começa com https://learn.microsoft.com/sql/ tem um parâmetro chamado ?view= acrescentado ao seu endereço. Esse valor de parâmetro é o código do moniker de controle de versão.

O código do moniker no endereço https sempre corresponde ao nome do moniker exibido no controle de versão.

Produtos, não edições

Edições

Nas décadas de 1990 e 2000, o Microsoft SQL Server tinha apenas um produto. Havia várias edições de cada versão do SQL Server, como as edições Developer e Enterprise do SQL Server 2008. As edições representavam conjuntos de recursos um pouco diferentes, mas o produto principal era o mesmo. Novas versões do SQL Server ainda podem ter uma variedade de edições.

Produtos

Com o aumento mais recente da computação em nuvem e do Microsoft Azure, a Microsoft lançou seu produto de Banco de Dados SQL do Azure. Embora haja bastante código compartilhado pelo produto local do SQL Server tradicional e pelo produto do Banco de Dados SQL do Azure, esses produtos são dois produtos realmente separados.

Para o SQL, os monikers de controle de versão fazem distinções entre produtos, mas não entre edições.

Produtos SQL de nuvem do Azure

Para artigos cujos endereços Web começam com https://learn.microsoft.com/sql/, quase todos se aplicam a pelo menos uma versão do produto chamado SQL Server. Um grande subconjunto desses artigos também se aplica a um ou mais dos nossos produtos de serviço do SQL hospedados em nossa nuvem do Azure. Um desses produtos de nuvem do SQL é chamado Banco de Dados SQL do Azure.

Naturalmente, o produto Banco de Dados SQL do Azure tem apenas uma versão. Quase todos os artigos que se aplicam ao Banco de Dados SQL do Azure, mas não ao SQL Server, têm endereços Web começando com https://learn.microsoft.com/azure/sql-database/.

Cenários de filtragem de versão

O sistema de controle de versão funciona filtrando todo o conteúdo da documentação que não se aplica ao moniker ativo no momento. Cada vez que você escolhe um moniker de controle de versão diferente, o conjunto de conteúdo oculto é alterado. A filtragem oculta o conteúdo nos seguintes níveis:

  • Seções ou sentenças dentro de um artigo.
  • Entradas de artigos no sumário.

Em seguida, há cenários que explicam os efeitos da escolha de um moniker diferente.

Cenário 1: Dentro do artigo atual

O cenário a seguir se concentra nas seções do artigo atual:

  1. O moniker de controle de versão atual é SQL Server 2017.
  2. Você está lendo uma seção que descreve um recurso que foi adicionado pela primeira vez à versão 2017 do SQL Server.
  3. Altere o moniker para SQL Server 2016.
  4. Você observa que a seção que estava lendo foi removida.
  5. Você altera novamente o moniker, desta vez para SQL Server 2019.
  6. Você percebe que a seção 2017 que estava lendo está de volta a ser exibida.

No cenário anterior, a seção sobre o novo recurso da versão 2017 provavelmente é marcada com um intervalo de moniker que inclui o seguinte código de moniker:

  • >=sql-server-2017

Quando o moniker do SQL Server 2019 foi escolhido, o sistema de controle de versão percebeu que 2019 é maior que ou igual a 2017 e exibiu a seção.

Cenário 2: Clicar em um link para um artigo oculto

O cenário incomum a seguir explica o que acontece se você clicar em um link para um artigo que está oculto no sumário no momento. Em resumo, o link funciona:

  1. O moniker de controle de versão atual é SQL Server 2017.
  2. No artigo atual A, você clica em um link para um artigo B que se aplica somente a SQL Server 2016.
    • Antes do clique, o sumário tem sua entrada para o artigo B oculto.
  3. Após o clique, o artigo B é exibido.
    • A exibição do artigo B força o controle de versão a mudar para o moniker do SQL Server 2016.
    • Porque o moniker original do SQL Server 2017 precisou ser abandonado. Esse abandono faz com que uma mensagem informativa seja exibida perto da parte superior da página da Web. A mensagem explica que o moniker atual precisava ser mudado para acomodar o novo artigo B.

Cenário 3: Navegar para um endereço HTTPS

O artigo a seguir foi adicionado como novo conteúdo para o SQL Server 2017. O artigo descreve os recursos que foram adicionados ao SQL Server na versão 2017. A maioria ou todos esses novos recursos também fazem parte da versão 2019. Aqui estão os atributos do artigo.

Atributo Valor
Title Novidades no SQL Server 2017
intervalo do moniker =">= sql-server-2017"
Endereço https https://learn.microsoft.com/sql/sql-server/what-s-new-in-sql-server-2017

Considerando o endereço https base, a tabela a seguir explica o que acontece quando o parâmetro ?view= é acrescentado pelo usuário e com vários valores.

Valor de ?view= Comportamento da navegação do endereço https
(Sem parâmetro.) O sistema de controle de versão experimenta seu valor de moniker padrão. Normalmente, o definimos para a versão mais recente que não seja de versão prévia do SQL Server.

Um padrão do SQL Server 2017 ou 2019 satisfaz o atributo >= sql-server-2017.

O sistema acrescenta o parâmetro ao endereço https, talvez como ?view=sql-server-2017.
O controle de lista suspensa do controle de versão é então definido como o nome do moniker de correspondência.
sql-server-2016 O sistema de controle de versão percebe que o intervalo do moniker do artigo não inclui a versão 2016.

O sistema escolhe um dos monikers que satisfaz o intervalo.

Em seguida, como no caso da versão 2016, o parâmetro ?view= é acrescentado e o nome do controle corresponde ao valor do parâmetro.
sql-server-2017 O sistema de controle de versão entende que o valor do parâmetro está incluído no intervalo do moniker do artigo.

O controle de versão é definido para corresponder ao valor do parâmetro.
sql-server-2019 O mesmo acontece para o caso do valor sql-server-2017, exceto que o parâmetro e o controle são definidos como 2019.

Todo o SQL – Não ocultar nada, moniker especial

Há um nome de produto de moniker especial de Todo o SQL e sua única versão é Não ocultar nada. A finalidade deste moniker é para o teste interno de determinadas alterações. Se for usado por um cliente, será mais provável que o moniker induza ao erro do que informe.

Alguns artigos têm informações relacionadas a várias versões do SQL Server. Cada moniker regular oculta seções com controle de versão que, de outra forma, podem exibir informações que são imprecisas, confusas ou contraditórias para a versão do moniker. O moniker Todo o SQL especial exibe todas as seções de versão e talvez não seja óbvio que informações imprecisas estão sendo exibidas.

Mensagem: A página solicitada não está disponível para o <moniker>

O cenário a seguir leva à exibição de uma mensagem informativa próxima à parte superior da página da Web Docs:

  1. No momento, o moniker de controle de versão é SQL Server 2017.
  2. Você está lendo um artigo que é relevante para o SQL Server 2017.
    • O artigo não é relevante para o produto Banco de Dados SQL do Azure.
  3. Você tenta alterar o moniker para Banco de Dados SQL do Azure – atual.
  4. Você vê que sua tentativa foi rejeitada e uma mensagem é exibida.

No final deste cenário, você verá a seguinte mensagem informativa exibida perto da parte superior da página da Web do Docs:

A página solicitada não está disponível para Banco de Dados SQL do Azure – atual. Você foi redirecionado para a versão mais recente do produto para a qual esta página está disponível.

A versão mais recente pode excluir versões que ainda não foram totalmente lançadas e estão com o status Versão prévia.

media_versioning-control-30-viewfallbackfrom.png

Versões anteriores do SQL Server

O sistema de controle de versão está totalmente implementado para a versão 2016 do SQL Server em diante.

Confira também

Versões anteriores do SQL Server, 2014 – 2005
Guia de navegação de documentos do SQL Server
Como contribuir com a documentação do SQL Server