Система управления версиями в документации по SQL
Область применения:
SQL Server База данных SQL Azure Azure Synapse Analytics Analytics Platform System (PDW)
В этой статье описывается система управления версиями в документации по SQL. Система управления версиями различает продукты и их версии. Она позволяет выбрать интересующий вас продукт и его версию. После этого выводится соответствующая документация.
Применимо к продуктам
В большинстве статей об SQL Server под заголовком есть строка, начинающаяся со слов Область применения. После них перечислены продукты SQL и указано, относится ли к ним статья. Например, статья может относиться к SQL Server, но не относиться к базе данных SQL Azure.
В строке Область примененияверсии продуктов не указываются. Мы стремимся избегать расхождений между содержимым строки Область применения и продуктами в конфигурациях системы управления версиями.
История отдельных наборов файлов
Для SQL Server 2014 и более ранних версий существует отдельная полная копия файлов документации для каждой версии. Например, разработка документации по SQL Server 2014 начиналась с копии документации по SQL Server 2012. Затем в процессе развития продукта копия для версии 2014 редактировалась.
При таком подходе, если в документации по версии 2014 обнаруживалась и устранялась ошибка, она могла сохраняться в документации по версиям 2012 и 2008. Это усложняло устранение ошибок и обслуживание в целом.
Один набор файлов для нескольких версий
По этой и другим причинам система была изменена так, что файлы документации по SQL Server 2016 также предназначены для версий 2017, 2019, а также, возможно, для <будущей версии> (vNext). Такое объединение стало возможным благодаря моникерам версий, которые назначаются файлам документации по SQL Server. Они назначаются или внедряются явным образом с любой степенью детализации, которая целесообразна для каждого конкретного файла документации.
Управление версиями в пользовательском интерфейсе
При просмотре любой статьи документации по SQL на веб-сайте Docs текущий выбранный моникер версии отображается над оглавлением. Этот элемент управления представляет собой раскрывающийся список.
Чтобы просмотреть документацию по другой версии SQL Server, щелкните стрелку вниз в конце моникера текущей версии. Затем выберите нужное сочетание продукта и версии. При выборе другой версии отображаемая документация меняется так, чтобы можно было увидеть отличия в новой выбранной версии. Изменения могут иметься или отсутствовать. Оба варианта вполне обычны.
Параметр HTTPS view=
К каждому веб-адресу статьи, начинающемуся с https://learn.microsoft.com/sql/, добавляется параметр ?view=. Его значение — это код моникера версии.
Код моникера в адресе https всегда соответствует имени моникера, отображаемому в элементу выбора версии.
Продукты и выпуски
Выпуски
В 1990-е и 2000-е годы Microsoft SQL Server был единственным продуктом SQL. Каждая версия SQL Server имела различные выпуски, например Developer и Enterprise для версии SQL Server 2008. Выпуски имели немного разные наборы возможностей, но базовый продукт был один и тот же. Новые версии SQL Server по-прежнему могут иметь несколько выпусков.
Продукты
С развитием облачных вычислений и платформы Microsoft Azure корпорация Майкрософт выпустила новый продукт "База данных SQL Azure". Хотя в традиционном локальном продукте SQL Server и базе данных SQL Azure много общего кода, это два отдельных продукта.
В документации по SQL с помощью моникеров версий различаются продукты, но не их выпуски.
Облачные продукты SQL Azure
Почти все статьи, веб-адрес которых начинается с https://learn.microsoft.com/sql/, относятся по крайней мере к одной версии продукта SQL Server. Значительная часть этих статей также относится к одному или нескольким продуктам SQL, размещенным в облаке Azure. Один из таких облачных продуктов SQL называется "База данных SQL Azure".
Разумеется, база данных SQL Azure имеет только одну версию. Почти все статьи, относящиеся к базе данных SQL Azure, но не к SQL Server, имеют веб-адрес, начинающийся с https://learn.microsoft.com/azure/sql-database/.
Сценарии фильтрации версий
Система управления версиями отфильтровывает все содержимое документации, которое не относится к текущему активному моникеру. Каждый раз при выборе другого моникера версии набор скрытого содержимого меняется. При фильтрации содержимое скрывается на следующих уровнях:
- разделы или предложения в статье;
- заголовки статей в оглавлении.
Ниже описывается, что происходит при выборе другого моникера.
Сценарий 1. В рамках текущей статьи
Ниже описывается, что происходит с разделами текущей статьи.
- Текущий моникер версии — SQL Server 2017.
- Вы читаете раздел, в котором описывается функция, появившаяся в SQL Server 2017.
- Вы меняете моникер на SQL Server 2016.
- Раздел, который вы читали, пропадает.
- Вы снова меняете моникер, на этот раз на SQL Server 2019.
- Раздел для версии 2017, который вы читали, снова появляется на экране.
В описанном выше сценарии раздел о новой функции в версии 2017, скорее всего, помечен диапазоном моникеров, включающим в себя следующий код моникера:
>=sql-server-2017
При выборе моникера SQL Server 2019 раздел отобразился, так как версия 2019 отвечает условию "больше или равно 2017".
Сценарий 2. Щелкните ссылку на скрытую статью
Ниже описывается, что происходит при выборе ссылки на статью, которая в настоящий момент скрыта в оглавлении (случается такое нечасто). Если говорить коротко, ссылка работает.
- Текущий моникер версии — SQL Server 2017.
- В текущей статье A вы щелкаете ссылку на статью B, которая относится только к SQL Server 2016.
- До щелчка статья B скрыта в оглавлении.
- После щелчка статья B появляется.
- Отображение статьи B приводит к тому, что система управления версиями переключается на моникер SQL Server 2016.
- Из-за этого исходный моникер SQL Server 2017 отменяется. По этой причине вверху веб-страницы выводится информационное сообщение. В сообщении поясняется, что текущий моникер пришлось сменить из-за перехода к статье B.
Сценарий 3. Переход к адресу https
Указанная ниже статья была добавлена для версии SQL Server 2017. В ней описываются возможности, появившиеся в SQL Server 2017. Большинство этих новых возможностей также имеются в версии 2019. Ниже приведены атрибуты статьи.
| Атрибут | Значение |
|---|---|
| Заголовок | Новые возможности SQL Server 2017 |
| диапазон моникеров | =">= sql-server-2017" |
адрес https |
https://learn.microsoft.com/sql/sql-server/what-s-new-in-sql-server-2017 |
В таблице ниже объясняется, что происходит при добавлении пользователем параметра ?view= с различными значениями к базовому адресу https.
Значение параметра ?view= |
Что происходит при переходе по адресу https |
|---|---|
| Параметр отсутствует | Система управления версиями пытается использовать значение моникера по умолчанию. Обычно это последняя не предварительная версия SQL Server. Атрибуту >= sql-server-2017 по умолчанию будет соответствовать версия SQL Server 2017 или 2019.Система добавит параметр к адресу https, например ?view=sql-server-2017.Пункт, выбранный в раскрывающемся списке версий, изменится в соответствии с именем моникера. |
sql-server-2016 |
Система управления версиями определит, что диапазон моникеров статьи не включает в себя версию 2016. Система выберет один из моникеров, входящих в диапазон. Затем, так же как в случае с версией 2016, будет добавлен параметр ?view= и в элементе управления будет выбран пункт, соответствующий значению параметра. |
sql-server-2017 |
Система управления версиями определяет, что значение параметра входит в диапазон моникеров статьи. В элементе управления версиями выбирается пункт, соответствующий значению параметра. |
sql-server-2019 |
То же, что и в случае со значением sql-server-2017, но параметр и элемент управления устанавливаются в значение 2019. |
Все SQL — скрыть ничего, специального моникера
Существует еще один специальный моникер с именем продукта All SQL (Все продукты SQL) и единственной версией Hide nothing (Ничего не скрывать). Он предназначен для внутреннего тестирования определенных изменений. При использовании клиентом этот моникер, скорее всего, будет вводить в заблуждение.
Некоторые статьи содержат сведения, относящиеся к нескольким версиям SQL Server. Обычный моникер скрывает разделы, сведения в которых являются неточными или противоречивыми для версии, соответствующей этому моникеру. При выборе специального моникера All SQL отображаются все разделы. При этом читателю может быть не очевидно, что отображается неточная информация.
Сообщение: запрошенная страница недоступна для <моникера>
В описанной ниже ситуации в верхней части веб-страницы Docs появляется информационное сообщение.
- Текущий моникер версии — SQL Server 2017.
- Вы читаете статью, относящуюся к SQL Server 2017.
- Эта статья не относится к базе данных SQL Azure.
- Вы пытаетесь изменить моникер на Azure SQL Database — current (База данных SQL Azure — текущая).
- Попытка отклоняется, и выводится сообщение.
В итоге в верхней части веб-страницы документации отображается следующее информационное сообщение:
Запрашиваемая страница недоступна для Azure SQL Database — current. Вы перенаправлены на последнюю версию продукта, для которой доступна эта страница.
При выборе последней версии могут исключаться версии, которые еще не выпущены окончательно и находятся в стадии предварительной версии.
Предыдущие версии SQL Server
Система управления версиями полностью реализована для SQL Server 2016 и последующих версий.
2012 и более ранних версий: система управления версиями не используется для SQL Server 2012 или более ранних версий.
- Специальный моникер SQL Server — older (SQL Server — более старые) скрывает почти все статьи. Исключениями являются несколько статей, которые иногда могут потребоваться пользователям старых версий.
- Предыдущие версии SQL Server: с 2005 по 2012
2014: система управления версиями реализована половина для SQL Server 2014. Вы можете выбрать SQL Server 2014 в системе управления версиями и получите результат. Однако на внутреннем уровне файлы для версии 2014 связаны только с ней, так же как файлы для версии 2008 связаны только с версией 2008.
2016 и более поздних версий: система управления версиями полностью реализована для SQL Server 2016 и более поздних версий.
См. также
Предыдущие версии SQL Server: с 2005 по 2014
Руководство по навигации в документации по SQL Server
Участие в работе над документацией по SQL Server