diff --git a/Documentation/dev/git/README.md b/Documentation/dev/git/README.md deleted file mode 100644 index 0dfcb86a3a445a71707899dbb941d8ec26e055f3..0000000000000000000000000000000000000000 --- a/Documentation/dev/git/README.md +++ /dev/null @@ -1,37 +0,0 @@ -VTK Git Usage -============= - -VTK version tracking and development is hosted by [Git](http://git-scm.com). -Please select a task for further instructions: - -Main Tasks ----------- -* [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - Git 1.7.2 or greater is preferred (required for development) - -* [Download VTK](download.md) - Users start here - -* [Develop VTK](develop.md) - Contributors start here - -Other Tasks ------------ - -* [Review Changes](https://gitlab.kitware.com/vtk/vtk/-/merge_requests) - - VTK GitLab Merge Requests - -* [Test VTK](dashboard.md) - CDash client setup - -* [Learn Git](http://public.kitware.com/Wiki/Git/Resources) - - Third-party documentation - -Branches --------- - -The upstream VTK repository has the following branches: - -* `master`: Development (default) -* `release`: Maintenance of latest release -* `nightly-master`: Follows `master`, updated at `01:00 UTC` -* `hooks`: Local commit hooks - ([placed](http://public.kitware.com/Wiki/Git/Hooks#Local) in `.git/hooks`) -* `dashboard`: Dashboard script ([setup](dashboard.md) a CDash client) diff --git a/Documentation/dev/git/dashboard.md b/Documentation/dev/git/dashboard.md deleted file mode 100644 index 796c45c10e63db5472cfd0afd6cf3f8b4a083053..0000000000000000000000000000000000000000 --- a/Documentation/dev/git/dashboard.md +++ /dev/null @@ -1,48 +0,0 @@ -Dashboard Scripts -================= - -This page documents how to use the VTK `dashboard` branch in [Git][]. -See the [README](README.md) for more information. - -[Git]: http://git-scm.com - -Using the Dashboard Scripts ---------------------------- - -The `dashboard` branch contains a dashboard client helper script. -Use these commands to track it: - - $ mkdir -p ~/Dashboards/VTKScripts - $ cd ~/Dashboards/VTKScripts - $ git init - $ git remote add -t dashboard origin https://gitlab.kitware.com/vtk/vtk.git - $ git pull origin - -The `vtk_common.cmake` script contains setup instructions in its -top comments. - -Update the `dashboard` branch to get the latest version of this -script by simply running: - - $ git pull - -Here is a link to the script as it appears today: [vtk_common.cmake][]. - -[vtk_common.cmake]: https://gitlab.kitware.com/vtk/vtk/-/tree/dashboard/vtk_common.cmake - -Changing the Dashboard Scripts ------------------------------- - -If you find bugs in the hooks themselves or would like to add new features, -the can be edited in the usual Git manner: - - $ git checkout -b my-topic-branch - -Make your edits, test it, and commit the result. Create a patch file with: - - $ git format-patch origin/dashboard - -And post the results in the [Development][] category in the [VTK Discourse][] forum. - -[Development]: https://discourse.vtk.org/c/development -[VTK Discourse]: https://discourse.vtk.org/ diff --git a/Documentation/dev/git/deprecation.md b/Documentation/dev/git/deprecation.md deleted file mode 100644 index 7b95657676099982139400fd7c302d01882f4b68..0000000000000000000000000000000000000000 --- a/Documentation/dev/git/deprecation.md +++ /dev/null @@ -1,77 +0,0 @@ -Deprecation Process -=================== - -This page documents how to deprecate an API and mark it as no longer necessary -for downstream consumers of VTK. - -Deprecating classes and methods -------------------------------- - -Classes, functions, and methods may be deprecated using the deprecation macros. - -```c++ -#include "vtkDeprecation.h" // Include the macros. - -// A deprecated class. -VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation") -class oldClass { -public: - // A deprecated method. - VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation") - void oldMethod(); -}; - -// A deprecated function. -VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation") -void oldFunction(); -``` - -The `X_Y_Z` should be the newest macro available in the `vtkDeprecation.h` -header when the API is added. - -Note that, unlike, the old `VTK_LEGACY_REMOVE` mechanism, the APIs are not -deleted. This does interfere with various kinds of deprecations. - - - *Changing the return type*: Don't do this. Use a new name for the - function/method. - - *Deprecating macros*: Use `VTK_LEGACY_REMOVE`. New macro APIs should be - highly discouraged. - -### Lifetime of deprecated APIs - -Deprecated APIs should exist for at least one release with the deprecation -warning active. This gives consumers of VTK at least one cycle to notice the -deprecation and move off of it. - -Upon branching for a release, `master` will soon after have all instances of -deprecated symbols removed. - -### Avoiding warnings within VTK - -VTK is providing the deprecated symbols and as such may still use them in tests -or implementations. Since these generate warnings when compiling VTK itself, -classes which define deprecated symbols must suppress them. - -Sources which continue to use the deprecated macros should add a comment to the -top of the source file to hide deprecation warnings in CI. - -```c++ -// Hide VTK_DEPRECATED_IN_X_Y_Z() warnings for this class. -#define VTK_DEPRECATION_LEVEL 0 -``` - -If one already exists, please add another comment to it so that when deprecated -symbols are removed, it shows up in the search. - -Using `VTK_DEPRECATION_LEVEL` ------------------------------ - -When using VTK, the `VTK_DEPRECATION_LEVEL` macro may be set to a version -number. APIs which have been deprecated after this point will not fire (as the -API is not deprecated as of the level requested). It should be defined using -the `VTK_VERSION_CHECK(major, minor, patch)` macro. - -Note that APIs on the verge of deletion (those deprecated in at least one -release) will always raise deprecation warnings. - -If not set, its value defaults to the current level of VTK. diff --git a/Documentation/dev/git/download.md b/Documentation/dev/git/download.md deleted file mode 100644 index 6d6616bb43b0b4186d6f26a3cac10854688e0d02..0000000000000000000000000000000000000000 --- a/Documentation/dev/git/download.md +++ /dev/null @@ -1,51 +0,0 @@ -Download VTK with Git -===================== - -This page documents how to download VTK source code through [Git][]. -See the [README](README.md) for more information. - -[Git]: http://git-scm.com - -Clone ------ - -Clone VTK using the commands: - - $ git clone https://gitlab.kitware.com/vtk/vtk.git VTK - $ cd VTK - $ git submodule update --init - -Update ------- - -Users that have made no local changes and simply want to update a -clone with the latest changes may run: - - $ git pull - -Avoid making local changes unless you have read our [developer instructions][]. - -[developer instructions]: develop.md - -Release -------- - -After cloning your local repository will be configured to follow the upstream -`master` branch by default. One may create a local branch to track the -upstream `release` branch instead, which should guarantee only bug fixes to -the functionality available in the latest release: - - $ git checkout --track -b release origin/release - -This local branch will always follow the latest release. -Use the [above instructions](#update) to update it. -Alternatively one may checkout a specific release tag: - - $ git checkout v6.2.0 - -Release tags never move. Repeat the command with a different tag to get a -different release. One may list available tags: - - $ git tag - -and then checkout any tag listed. diff --git a/Documentation/dev/release_process.md b/Documentation/dev/release_process.md deleted file mode 100644 index 3ca63e73590960f241b7e7d8a6c3276c716b4fb1..0000000000000000000000000000000000000000 --- a/Documentation/dev/release_process.md +++ /dev/null @@ -1,171 +0,0 @@ -# Release Process - -This document provides a high-level overview of the VTK release cycle and -associated release process. - -## Overview - -We aim to release a new version of VTK every six months. However, we recognize -that this schedule is flexible. The project is funded and developed by many -different groups, each of which works towards their own particular sets of -features. - -VTK releases are named with a `Major.Minor.Patch` scheme. - -## Branching Scheme - -The overall release history resembles a skinny tree. Development proceeds along -the `master` branch, consisting of topic branches that start from and are merged -into `master`. Every so often, a release is tagged and branched from it. - -In general, no work takes place on the `release` branch, other than the handful -of important patches that make up occasional patch releases. - -:::{hint} -Steps for contributing changes specific to the `release` branch are documented in -[](git/develop.md#create-a-topic). -::: - -On the `master` branch, bug fixes and new features are continuously -developed. At release time, the focus temporarily shifts to producing -a library that is as stable and robust as possible. - -## Steps - -The process for cutting releases is as follows: - -1. Announce upcoming release - - A few weeks before the intended `release` branch, announce on [VTK Discourse](https://discourse.vtk.org/) - that a new release is coming. This alerts developers to avoid making drastic - changes that might delay the release and gives them a chance to push important - and nearly completed features in time for the release. For example, - see [this post](https://discourse.vtk.org/t/vtk-9-2-0-release-cycle/8149). - -2. Polish the dashboards and bug tracker by addressing outstanding issue and - coordinate effort with relevant developers. - - Persistent compilation and regression test problems are fixed. Serious - outstanding bugs are fixed. - -3. [Create a new issue](https://gitlab.kitware.com/vtk/vtk/-/issues/new) titled - `Release X.Y.Z[rcN]` based of the [new-release](https://gitlab.kitware.com/vtk/vtk/-/blob/master/.gitlab/issue_templates/new-release.md?plain=1) template. - - :::{Important} - Specific steps to create eiter the candidate or the official release are found - in the newly created issue. - ::: - -4. Perform the release candidate cycle - - 1. Tag the release branch and create and publish release candidate - artifacts and change summaries. - - 2. Announce the release candidate and request feedback from the - community, especially third-party packagers. - - :::{hint} - Bug reports should be entered into the bug tracker with the upcoming - release number as the milestone. - ::: - - 3. If the community reports bugs, classify them in the bug tracker and ensure - they are fixed. - - Only serious bugs and regressions need to be fixed before the release. - New features and minor problems should be merged into `master` as usual. - - Patches for the release branch should start from the release branch, be - submitted through GitLab, and then merged into `master`. Once fully - tested there, the branch can be merged into the release branch. - - When the selected issues are fixed in the release branch, tag the tip - of the release branch and release it as the next candidate, then the - cycle continues. - - 4. Distribution specific patches can accumulate over time. Consider reviewing the - following distribution specific pages to identify potential fixes and improvements - that could be integrated in VTK itself: - - * Debian: - - https://tracker.debian.org/pkg/vtk9 - - https://udd.debian.org/patches.cgi?src=vtk9 - - * Gentoo: - - https://packages.gentoo.org/packages/sci-libs/vtk - - https://gitweb.gentoo.org/repo/gentoo.git/tree/sci-libs/vtk/files - - * openSUSE: - - https://build.opensuse.org/package/show/openSUSE:Factory/vtk - -5. Package the official release - - The official VTK package consists of tar balls and ZIP files of the source, - Python Wheels, Doxygen documentation, and regression test data, all at the - tag point. - - Volunteer third-party packagers create binary packages from the official - release for various platforms, so their input is especially valuable during - the release cycle. - - The release manager also compiles release notes for the official release - announcement. Release notes are compiled from various [standardized topic documents](https://gitlab.kitware.com/vtk/vtk/-/tree/master/Documentation/release) - added to the `Documentation/release/dev` folder while features or issues - are fixed. The aggregation of these topic files is done manually and - results in the creation of a file named `Documentation/release/X.Y.md` for - the current release. - -## GitLab and Releases - -GitLab milestones are used for keeping track of branches for the release. They -allow keeping track of issues and merge requests which should be "done" for -the milestone to be considered complete. - -For each release (including release candidates), a milestone is created with a -plausible due date. The milestone page allows for an easy overview of branches -which need wrangling for a release. - -### Merge Requests - -Merge requests which need to be rebased onto the relevant release branch -should be marked with the `needs-rebase-for-release` tag and commented on how -the branch can be rebased properly: - - This branch is marked for a release, but includes other commits in - `master`. Please either rebase the branch on top of the release branch and - remove the `needs-rebase-for-release` tag from the merge request: - - ```sh - $ git rebase --onto=origin/release origin/master $branch_name - $ git gitlab-push -f - ``` - - or, if there are conflicts when using a single branch, open a new branch - and open a merge request against the `release` branch: - - ```sh - $ git checkout -b ${branch_name}-release $branch_name - $ git rebase --onto=origin/release origin/master ${branch_name}-release - $ git gitlab-push - ``` - - Thanks! - -### Wrangling Branches - -Branches may be wrangled using the filters in the merge request page. Replace -`$release` at the end with the relevant milestone name: - - https://gitlab.kitware.com/vtk/vtk/-/merge_requests?state=all&milestone_title=$release - -The following states of a merge request indicate where they are in the flow: - - - open for `master`: get into `master` first - - open for `release`: ensure it is already in `master` - - open with `needs-rebase-for-release` tag: wait for contributor to rebase - properly; ping if necessary - - `MERGED`: merge into `release` - -There is currently no good way of marking a branch that went towards `master` -is also in `release` already since tags cannot be added to closed merge -requests. Suggestions welcome :) . diff --git a/Documentation/dev/testing.md b/Documentation/dev/testing.md deleted file mode 100644 index 34d16abce356511fbdf3a84de7a41ad1c2a8ce2d..0000000000000000000000000000000000000000 --- a/Documentation/dev/testing.md +++ /dev/null @@ -1,38 +0,0 @@ -# Regression Testing - -## Testing and dashboard submitter setup - -Regression testing in VTK takes the form of a set of programs, that are included in the VTK source code and enabled in builds configured through CMake to have the `VTK_BUILD_TESTING` flag turned on. Test pass/fail results are returned to CTest via a test program's exit code. VTK contains helper classes that do specific checks, such as comparing a produced image against a known valid one, that are used in many of the regression tests. Test results may be submitted to Kitware's CDash instance, were they will be gathered and displayed at <http://open.cdash.org/index.php?project=VTK> - -All proposed changes to VTK are automatically tested on Windows, Mac and Linux machines. All changes that are merged into the master branch are subsequently tested again by more rigorously configured Windows, Mac and Linux continuous dashboard submitters. After 9PM Eastern Time, the master branch is again tested by a wider set of machines and platforms. These results appear in the next day's page. - -At each step in the code integration path the developers who contribute and merge code are responsible for checking the test results to look for problems that the new code might have introduced. Plus signs in CDash indicate newly detected problems. Developers can correlate problems with contributions by logging in to CDash. Submissions that contain a logged in developer's change are highlighted with yellow dots. - -It is highly recommended that developers test changes locally before submitting them. To run tests locally: - -1. Configure with `VTK_BUILD_TESTING` set ON - - The exact set of tests created depends on many configuration options. Tests in non-default modules are only tested when those modules are purposefully enabled, the smoke tests described in the Coding Style section above are enabled only when the python or Tcl interpreter is installed, tests written in wrapped languages are only enabled when wrapping is turned on, etc. - -1. Build. - - VTK tests are only available from the build tree. - -1. Run ctest at the command line in the build directory or make the TESTING target in Visual Studio. - - As ctest runs the tests it prints a summary. You should expect 90% of the tests or better to pass if your VTK is configured correctly. Detailed results (which are also printed if you supply a --V argument to ctest) are put into the Testing/Temporary directory. The detailed results include the command line that ctest uses to spawn each test. Other particularly useful arguments are: - ```bash - --R TestNameSubstringToInclude to choose tests by name - - --E TestNameSubstringToExclude to reject tests by name - - --I start,stop,step to run a portion of the tests - - --j N to run N tests simultaneously. - ``` - -Dashboard submitting machines work at a slightly higher level of abstraction that adds the additional stages of downloading, configuring and building VTK before running the tests, and submitting all results to CDash afterward. With a build tree in place you can run "ctest --D Experimental" to run at this level and submit the results to the experimental section of the VTK dashboard or "ctest --M Experimental -T Build --T Submit" etc to pick and choose from among the stages. When setting up a test submitter machine one should start with the experimental configuration and then, once the kinks are worked out, promote the submitter to the Nightly section. - -The volunteer machines use cron or Windows task scheduler to run CMake scripts that configure a VTK build with specific options, and then run ctest --D as above. Within CDash, you can see each test machine's specific configuration by clicking on the Advanced View and then clicking on the note icon in the Build Name column. This is a useful starting point when setting up a new submitter. It is important that each submitter's dashboard script include the name of the person who configures or maintains the machine so that, when the machine has problems, the dashboard maintainer can address it. - -For details about the Continuous Integration infrastructure hosted at Kitware see [here](git/develop.md#continuous-integration). diff --git a/Documentation/docs/developers_guide/git/README.md b/Documentation/docs/developers_guide/git/README.md index cfeda9fd7af8440c96383ef6a7ada4fd6ea20f48..21b7c4b18d5fb9234204c65dae75f9f5865304c8 100644 --- a/Documentation/docs/developers_guide/git/README.md +++ b/Documentation/docs/developers_guide/git/README.md @@ -2,6 +2,40 @@ orphan: true --- -```{include} ../../../dev/git/README.md -:relative-docs: . -``` +VTK Git Usage +============= + +VTK version tracking and development is hosted by [Git](http://git-scm.com). +Please select a task for further instructions: + +Main Tasks +---------- +* [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + Git 1.7.2 or greater is preferred (required for development) + +* [Download VTK](download.md) - Users start here + +* [Develop VTK](develop.md) - Contributors start here + +Other Tasks +----------- + +* [Review Changes](https://gitlab.kitware.com/vtk/vtk/-/merge_requests) - + VTK GitLab Merge Requests + +* [Test VTK](dashboard.md) - CDash client setup + +* [Learn Git](http://public.kitware.com/Wiki/Git/Resources) - + Third-party documentation + +Branches +-------- + +The upstream VTK repository has the following branches: + +* `master`: Development (default) +* `release`: Maintenance of latest release +* `nightly-master`: Follows `master`, updated at `01:00 UTC` +* `hooks`: Local commit hooks + ([placed](http://public.kitware.com/Wiki/Git/Hooks#Local) in `.git/hooks`) +* `dashboard`: Dashboard script ([setup](dashboard.md) a CDash client) diff --git a/Documentation/docs/developers_guide/git/dashboard.md b/Documentation/docs/developers_guide/git/dashboard.md index faff643d5085c9a69d3cf04c66f933a832c32205..796c45c10e63db5472cfd0afd6cf3f8b4a083053 100644 --- a/Documentation/docs/developers_guide/git/dashboard.md +++ b/Documentation/docs/developers_guide/git/dashboard.md @@ -1,3 +1,48 @@ -```{include} ../../../dev/git/dashboard.md -:relative-docs: . -``` +Dashboard Scripts +================= + +This page documents how to use the VTK `dashboard` branch in [Git][]. +See the [README](README.md) for more information. + +[Git]: http://git-scm.com + +Using the Dashboard Scripts +--------------------------- + +The `dashboard` branch contains a dashboard client helper script. +Use these commands to track it: + + $ mkdir -p ~/Dashboards/VTKScripts + $ cd ~/Dashboards/VTKScripts + $ git init + $ git remote add -t dashboard origin https://gitlab.kitware.com/vtk/vtk.git + $ git pull origin + +The `vtk_common.cmake` script contains setup instructions in its +top comments. + +Update the `dashboard` branch to get the latest version of this +script by simply running: + + $ git pull + +Here is a link to the script as it appears today: [vtk_common.cmake][]. + +[vtk_common.cmake]: https://gitlab.kitware.com/vtk/vtk/-/tree/dashboard/vtk_common.cmake + +Changing the Dashboard Scripts +------------------------------ + +If you find bugs in the hooks themselves or would like to add new features, +the can be edited in the usual Git manner: + + $ git checkout -b my-topic-branch + +Make your edits, test it, and commit the result. Create a patch file with: + + $ git format-patch origin/dashboard + +And post the results in the [Development][] category in the [VTK Discourse][] forum. + +[Development]: https://discourse.vtk.org/c/development +[VTK Discourse]: https://discourse.vtk.org/ diff --git a/Documentation/docs/developers_guide/git/deprecation.md b/Documentation/docs/developers_guide/git/deprecation.md index f0f5ea7154bfaca569f9d0ada8a8f99c64cb8d68..7b95657676099982139400fd7c302d01882f4b68 100644 --- a/Documentation/docs/developers_guide/git/deprecation.md +++ b/Documentation/docs/developers_guide/git/deprecation.md @@ -1,2 +1,77 @@ -```{include} ../../../dev/git/deprecation.md +Deprecation Process +=================== + +This page documents how to deprecate an API and mark it as no longer necessary +for downstream consumers of VTK. + +Deprecating classes and methods +------------------------------- + +Classes, functions, and methods may be deprecated using the deprecation macros. + +```c++ +#include "vtkDeprecation.h" // Include the macros. + +// A deprecated class. +VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation") +class oldClass { +public: + // A deprecated method. + VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation") + void oldMethod(); +}; + +// A deprecated function. +VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation") +void oldFunction(); ``` + +The `X_Y_Z` should be the newest macro available in the `vtkDeprecation.h` +header when the API is added. + +Note that, unlike, the old `VTK_LEGACY_REMOVE` mechanism, the APIs are not +deleted. This does interfere with various kinds of deprecations. + + - *Changing the return type*: Don't do this. Use a new name for the + function/method. + - *Deprecating macros*: Use `VTK_LEGACY_REMOVE`. New macro APIs should be + highly discouraged. + +### Lifetime of deprecated APIs + +Deprecated APIs should exist for at least one release with the deprecation +warning active. This gives consumers of VTK at least one cycle to notice the +deprecation and move off of it. + +Upon branching for a release, `master` will soon after have all instances of +deprecated symbols removed. + +### Avoiding warnings within VTK + +VTK is providing the deprecated symbols and as such may still use them in tests +or implementations. Since these generate warnings when compiling VTK itself, +classes which define deprecated symbols must suppress them. + +Sources which continue to use the deprecated macros should add a comment to the +top of the source file to hide deprecation warnings in CI. + +```c++ +// Hide VTK_DEPRECATED_IN_X_Y_Z() warnings for this class. +#define VTK_DEPRECATION_LEVEL 0 +``` + +If one already exists, please add another comment to it so that when deprecated +symbols are removed, it shows up in the search. + +Using `VTK_DEPRECATION_LEVEL` +----------------------------- + +When using VTK, the `VTK_DEPRECATION_LEVEL` macro may be set to a version +number. APIs which have been deprecated after this point will not fire (as the +API is not deprecated as of the level requested). It should be defined using +the `VTK_VERSION_CHECK(major, minor, patch)` macro. + +Note that APIs on the verge of deletion (those deprecated in at least one +release) will always raise deprecation warnings. + +If not set, its value defaults to the current level of VTK. diff --git a/Documentation/docs/developers_guide/git/download.md b/Documentation/docs/developers_guide/git/download.md index 951a7e556395a18c66afc3749271ae29e3a70b91..78019ea2f070c54059d8b7c315813f242c35799c 100644 --- a/Documentation/docs/developers_guide/git/download.md +++ b/Documentation/docs/developers_guide/git/download.md @@ -2,5 +2,54 @@ orphan: true --- -```{include} ../../../dev/git/download.md -``` +Download VTK with Git +===================== + +This page documents how to download VTK source code through [Git][]. +See the [README](README.md) for more information. + +[Git]: http://git-scm.com + +Clone +----- + +Clone VTK using the commands: + + $ git clone https://gitlab.kitware.com/vtk/vtk.git VTK + $ cd VTK + $ git submodule update --init + +Update +------ + +Users that have made no local changes and simply want to update a +clone with the latest changes may run: + + $ git pull + +Avoid making local changes unless you have read our [developer instructions][]. + +[developer instructions]: develop.md + +Release +------- + +After cloning your local repository will be configured to follow the upstream +`master` branch by default. One may create a local branch to track the +upstream `release` branch instead, which should guarantee only bug fixes to +the functionality available in the latest release: + + $ git checkout --track -b release origin/release + +This local branch will always follow the latest release. +Use the [above instructions](#update) to update it. +Alternatively one may checkout a specific release tag: + + $ git checkout v6.2.0 + +Release tags never move. Repeat the command with a different tag to get a +different release. One may list available tags: + + $ git tag + +and then checkout any tag listed. diff --git a/Documentation/docs/developers_guide/release_process.md b/Documentation/docs/developers_guide/release_process.md index 19cd8d6721e3649e3fd51387978f4412a273f70c..3ca63e73590960f241b7e7d8a6c3276c716b4fb1 100644 --- a/Documentation/docs/developers_guide/release_process.md +++ b/Documentation/docs/developers_guide/release_process.md @@ -1,2 +1,171 @@ -```{include} ../../dev/release_process.md -``` +# Release Process + +This document provides a high-level overview of the VTK release cycle and +associated release process. + +## Overview + +We aim to release a new version of VTK every six months. However, we recognize +that this schedule is flexible. The project is funded and developed by many +different groups, each of which works towards their own particular sets of +features. + +VTK releases are named with a `Major.Minor.Patch` scheme. + +## Branching Scheme + +The overall release history resembles a skinny tree. Development proceeds along +the `master` branch, consisting of topic branches that start from and are merged +into `master`. Every so often, a release is tagged and branched from it. + +In general, no work takes place on the `release` branch, other than the handful +of important patches that make up occasional patch releases. + +:::{hint} +Steps for contributing changes specific to the `release` branch are documented in +[](git/develop.md#create-a-topic). +::: + +On the `master` branch, bug fixes and new features are continuously +developed. At release time, the focus temporarily shifts to producing +a library that is as stable and robust as possible. + +## Steps + +The process for cutting releases is as follows: + +1. Announce upcoming release + + A few weeks before the intended `release` branch, announce on [VTK Discourse](https://discourse.vtk.org/) + that a new release is coming. This alerts developers to avoid making drastic + changes that might delay the release and gives them a chance to push important + and nearly completed features in time for the release. For example, + see [this post](https://discourse.vtk.org/t/vtk-9-2-0-release-cycle/8149). + +2. Polish the dashboards and bug tracker by addressing outstanding issue and + coordinate effort with relevant developers. + + Persistent compilation and regression test problems are fixed. Serious + outstanding bugs are fixed. + +3. [Create a new issue](https://gitlab.kitware.com/vtk/vtk/-/issues/new) titled + `Release X.Y.Z[rcN]` based of the [new-release](https://gitlab.kitware.com/vtk/vtk/-/blob/master/.gitlab/issue_templates/new-release.md?plain=1) template. + + :::{Important} + Specific steps to create eiter the candidate or the official release are found + in the newly created issue. + ::: + +4. Perform the release candidate cycle + + 1. Tag the release branch and create and publish release candidate + artifacts and change summaries. + + 2. Announce the release candidate and request feedback from the + community, especially third-party packagers. + + :::{hint} + Bug reports should be entered into the bug tracker with the upcoming + release number as the milestone. + ::: + + 3. If the community reports bugs, classify them in the bug tracker and ensure + they are fixed. + + Only serious bugs and regressions need to be fixed before the release. + New features and minor problems should be merged into `master` as usual. + + Patches for the release branch should start from the release branch, be + submitted through GitLab, and then merged into `master`. Once fully + tested there, the branch can be merged into the release branch. + + When the selected issues are fixed in the release branch, tag the tip + of the release branch and release it as the next candidate, then the + cycle continues. + + 4. Distribution specific patches can accumulate over time. Consider reviewing the + following distribution specific pages to identify potential fixes and improvements + that could be integrated in VTK itself: + + * Debian: + - https://tracker.debian.org/pkg/vtk9 + - https://udd.debian.org/patches.cgi?src=vtk9 + + * Gentoo: + - https://packages.gentoo.org/packages/sci-libs/vtk + - https://gitweb.gentoo.org/repo/gentoo.git/tree/sci-libs/vtk/files + + * openSUSE: + - https://build.opensuse.org/package/show/openSUSE:Factory/vtk + +5. Package the official release + + The official VTK package consists of tar balls and ZIP files of the source, + Python Wheels, Doxygen documentation, and regression test data, all at the + tag point. + + Volunteer third-party packagers create binary packages from the official + release for various platforms, so their input is especially valuable during + the release cycle. + + The release manager also compiles release notes for the official release + announcement. Release notes are compiled from various [standardized topic documents](https://gitlab.kitware.com/vtk/vtk/-/tree/master/Documentation/release) + added to the `Documentation/release/dev` folder while features or issues + are fixed. The aggregation of these topic files is done manually and + results in the creation of a file named `Documentation/release/X.Y.md` for + the current release. + +## GitLab and Releases + +GitLab milestones are used for keeping track of branches for the release. They +allow keeping track of issues and merge requests which should be "done" for +the milestone to be considered complete. + +For each release (including release candidates), a milestone is created with a +plausible due date. The milestone page allows for an easy overview of branches +which need wrangling for a release. + +### Merge Requests + +Merge requests which need to be rebased onto the relevant release branch +should be marked with the `needs-rebase-for-release` tag and commented on how +the branch can be rebased properly: + + This branch is marked for a release, but includes other commits in + `master`. Please either rebase the branch on top of the release branch and + remove the `needs-rebase-for-release` tag from the merge request: + + ```sh + $ git rebase --onto=origin/release origin/master $branch_name + $ git gitlab-push -f + ``` + + or, if there are conflicts when using a single branch, open a new branch + and open a merge request against the `release` branch: + + ```sh + $ git checkout -b ${branch_name}-release $branch_name + $ git rebase --onto=origin/release origin/master ${branch_name}-release + $ git gitlab-push + ``` + + Thanks! + +### Wrangling Branches + +Branches may be wrangled using the filters in the merge request page. Replace +`$release` at the end with the relevant milestone name: + + https://gitlab.kitware.com/vtk/vtk/-/merge_requests?state=all&milestone_title=$release + +The following states of a merge request indicate where they are in the flow: + + - open for `master`: get into `master` first + - open for `release`: ensure it is already in `master` + - open with `needs-rebase-for-release` tag: wait for contributor to rebase + properly; ping if necessary + - `MERGED`: merge into `release` + +There is currently no good way of marking a branch that went towards `master` +is also in `release` already since tags cannot be added to closed merge +requests. Suggestions welcome :) . diff --git a/Documentation/docs/developers_guide/testing.md b/Documentation/docs/developers_guide/testing.md index 49f344f6ffb9579021211bb7ef7cf80a0406b3ab..34d16abce356511fbdf3a84de7a41ad1c2a8ce2d 100644 --- a/Documentation/docs/developers_guide/testing.md +++ b/Documentation/docs/developers_guide/testing.md @@ -1,3 +1,38 @@ -```{include} ../../dev/testing.md -:relative-docs: . -``` +# Regression Testing + +## Testing and dashboard submitter setup + +Regression testing in VTK takes the form of a set of programs, that are included in the VTK source code and enabled in builds configured through CMake to have the `VTK_BUILD_TESTING` flag turned on. Test pass/fail results are returned to CTest via a test program's exit code. VTK contains helper classes that do specific checks, such as comparing a produced image against a known valid one, that are used in many of the regression tests. Test results may be submitted to Kitware's CDash instance, were they will be gathered and displayed at <http://open.cdash.org/index.php?project=VTK> + +All proposed changes to VTK are automatically tested on Windows, Mac and Linux machines. All changes that are merged into the master branch are subsequently tested again by more rigorously configured Windows, Mac and Linux continuous dashboard submitters. After 9PM Eastern Time, the master branch is again tested by a wider set of machines and platforms. These results appear in the next day's page. + +At each step in the code integration path the developers who contribute and merge code are responsible for checking the test results to look for problems that the new code might have introduced. Plus signs in CDash indicate newly detected problems. Developers can correlate problems with contributions by logging in to CDash. Submissions that contain a logged in developer's change are highlighted with yellow dots. + +It is highly recommended that developers test changes locally before submitting them. To run tests locally: + +1. Configure with `VTK_BUILD_TESTING` set ON + + The exact set of tests created depends on many configuration options. Tests in non-default modules are only tested when those modules are purposefully enabled, the smoke tests described in the Coding Style section above are enabled only when the python or Tcl interpreter is installed, tests written in wrapped languages are only enabled when wrapping is turned on, etc. + +1. Build. + + VTK tests are only available from the build tree. + +1. Run ctest at the command line in the build directory or make the TESTING target in Visual Studio. + + As ctest runs the tests it prints a summary. You should expect 90% of the tests or better to pass if your VTK is configured correctly. Detailed results (which are also printed if you supply a --V argument to ctest) are put into the Testing/Temporary directory. The detailed results include the command line that ctest uses to spawn each test. Other particularly useful arguments are: + ```bash + --R TestNameSubstringToInclude to choose tests by name + + --E TestNameSubstringToExclude to reject tests by name + + --I start,stop,step to run a portion of the tests + + --j N to run N tests simultaneously. + ``` + +Dashboard submitting machines work at a slightly higher level of abstraction that adds the additional stages of downloading, configuring and building VTK before running the tests, and submitting all results to CDash afterward. With a build tree in place you can run "ctest --D Experimental" to run at this level and submit the results to the experimental section of the VTK dashboard or "ctest --M Experimental -T Build --T Submit" etc to pick and choose from among the stages. When setting up a test submitter machine one should start with the experimental configuration and then, once the kinks are worked out, promote the submitter to the Nightly section. + +The volunteer machines use cron or Windows task scheduler to run CMake scripts that configure a VTK build with specific options, and then run ctest --D as above. Within CDash, you can see each test machine's specific configuration by clicking on the Advanced View and then clicking on the note icon in the Build Name column. This is a useful starting point when setting up a new submitter. It is important that each submitter's dashboard script include the name of the person who configures or maintains the machine so that, when the machine has problems, the dashboard maintainer can address it. + +For details about the Continuous Integration infrastructure hosted at Kitware see [here](git/develop.md#continuous-integration).