Commit 4504da80 authored by Bob Obara's avatar Bob Obara

DOC: Adding Software Process Documentation

Adding general documentation to SMTK
parent 444586f9
Contributing to SMTK
This page documents at a very high level how to contribute to SMTK.
Please check our [developer instructions][] for a more detailed guide to
developing and contributing to the project, and our [SMTK Git README][]
for additional information.
The SMTK development cycle is built upon the following components:
1. [Issues][] identify any issues including bugs and feature requests. In
general, every code change should have an associated issue which identifies
the bug being fixed or the feature being added.
2. [Merge Requests][] are collections of changes that address issues.
3. [Labels][] are labels or tags that can be added and removed to/from issues
and/or merge requests to annotate them including indicating their state in
the development cycle. See [Labels Glossary][].
4. [Milestones][] refer to development milestones such as numbered public
releases, or named internal releases.
Reporting Issues
If you have a bug report or a feature request for SMTK, you can use the
[issues][] tracker to report a [new issue][].
To report an issue.
1. Register for an account on [our GitLab instance][GitLab Access] and select a user name.
2. Create a [new issue][].
3. Ensure that the issue has a **Title** and **Description**
with enough details for someone from the development team to reproduce the
issue. See [Gitlab Markdown] guide for styling the **Description**. Include
screenshots and sample datasets whenever possible. Typically, reporter
**should not** set any other fields for the issue, including
**Assignee**, **Milestone**, or **Labels**. These get set by members of the
development team.
4. If developers need more information on an issue, they will add the
`triage:needinfo` label as add a comment for the reporter soliciting more
information. Once the reporter has provided the necessary information, he or she
should remove the `triage:needinfo` label from the issue to notify the
development team.
When a developer starts working on an issue, the developer will add the
`workflow:active-development` label. Once the development is complete and the issue
resolved, the issue will be closed, and the `workflow:active-development` label
will be replaced by `workflow:customer-review`. At that point, the reporter can
checkout the latest `master` and confirm that the issue has been addressed. If so,
the reporter can remove the `workflow:customer-review` label. If the issue was not
addressed then the reporter should reopen the issue or solicit more information
from the developer by adding the `triage:needinfo` label.
To keep the number of open issues manageable, we will periodically expire old issues
with no activity. Such issues will be closed and tagged with the label
`triage:expired`. Such issues can be reopened if needed.
Notes for Project Managers
For every issue, project managers can assign:
1. **Milestone** to indicate which release this issue fix is planned for.
2. `priority:...` label to indicate how critical is this issue for the specific
milestone, ranging from `priority:required`, `priority:important`,
`priority:nice-to-have`, and `priority:low`. Only one priority label makes
sense at a time.
Notes for Developers
For every issue, developers can assign:
1. `area:...` labels to indicate which area this issue relates to in terms of the software process e.g. `area:build`,
`area:doc`, etc.
2. `component:...` label to indicate which component of SMTK is effected by this issue. For example `component:attribute-system` refers to the SMTK's attribute system while `component:gui` refers to SMTK's Qt GUI's extensions.
3. `triage:...` labels to indicate issue triage status. `triage:confirmed` is added
when the issue has been confirmed. `triage:easy` is added for issues that are
easy to fix. `triage:feature` is added to issues that are new feature requests.
`triage:needinfo` is added to solicit more information from the reporter.
4. `triage:needinfo` label on closed issues means the reporter or reviewer is
requesting more information from the developer before the fix can be reviewed.
Please provide such information and then remove the label.
5. `workflow:active-development` label should be added to issues under development.
Fixing Issues
Typically, one addresses issues by writing code. To start contributing to SMTK:
1. Register for an account on [our GitLab instance][GitLab Access] and select a user name.
2. [Fork SMTK][] into your user's namespace on GitLab.
3. Create a local clone of the main SMTK repository. Optionally configure
Git to [use SSH instead of HTTPS][].
Then clone:
$ git clone --recursive SMTK
$ cd SMTK
The main repository will be configured as your `origin` remote.
For more information see: [Setup][] and [download instructions][]
4. Run the [developer setup script][] to prepare your SMTK work
tree and create Git command aliases used below:
$ ./utilities/
This will prompt for your GitLab user name and configure a remote
called `gitlab` to refer to it.
For more information see: [Setup][]
5. [Build SMTK].
6. Edit files and create commits (repeat as needed):
$ edit file1 file2 file3
$ git add file1 file2 file3
$ git commit
Commit messages must be thorough and informative so that
reviewers will have a good understanding of why the change is
needed before looking at the code. Appropriately refer to the issue
number, if applicable.
For more information see: [Create a Topic][]
7. Push commits in your topic branch to your fork in GitLab:
$ git gitlab-push
For more information see: [Share a Topic][]
8. Run tests with ctest, or use the dashboard
9. Visit your fork in GitLab, browse to the "**Merge Requests**" link on the
left, and use the "**New Merge Request**" button in the upper right to
create a Merge Request.
For more information see: [Create a Merge Request][]
8. Follow the [review][] process to get your merge request reviewed and tested.
On success, the merge-request can be merged and closed.
For more information see: [Review a Merge Request][]
9. When a merge request is closed, any related issue should be closed (if not
closed automatically) and assigned the `workflow:customer-review` label to
request a review from the reporter.
10. Monitor the related issue for any `triage:needinfo` label additions to provide
the customer with any details necessary to test the fix.
Our [wiki][] is used to document features, flesh out designs and host other
documentation. We have several [mailing lists][] to coordinate development and
to provide support.
[SMTK Git README]: doc/dev/
[developer instructions]: doc/dev/
[GitLab Access]:
[Fork SMTK]:
[use SSH instead of HTTPS]: doc/dev/
[download instructions]: doc/dev/
[developer setup script]: Utilities/
[Setup]: doc/dev/
[Build SMTK]: doc/dev/
[Create a Topic]: doc/dev/
[Share a Topic]: doc/dev/
[Create a Merge Request]: doc/dev/
[Review a Merge Request]: doc/dev/
[review]: doc/dev/
[Merge Requests]:
[Mailing Lists]:
[Gitlab Markdown]:
[new issue]:
[Labels Glossary]: doc/dev/
The [Simulation Model Toolkit (SMTK)][SMTK] is an open-source, multi-platform toolkit for supporting simulation workflows by providing access to different modeling kernels, mesh databases, and simulation infomation (via its attribute system). SMTK is developed as part of the [Computational Model Builder (CMB)][CMB] effort and provides extensions for [ParaView][],
[Visualization Toolkit (VTK)][VTK] and [Qt][].
The project
has grown through collaborative efforts between [Kitware Inc.][Kitware],
and various other
government and commercial institutions, and acedemic partners.
Learning Resources
* General information is available at the [SMTK Homepage][SMTK].
* Documentation is available [online][Documentation].
* Community discussion takes place on the [SMTK Mailing Lists][].
* Commercial [support][Kitware Support] and [training][Kitware Training]
are available from [Kitware][].
[CMB Homepage]:
[SMTK Mailing Lists]:
[Kitware Support]:
[Kitware Training]:
Reporting Bugs
If you have found a bug:
1. If you have a patch, please read the [][] document.
2. Otherwise, please join the one of the [SMTK Mailing Lists][] and ask
about the expected and observed behaviors to determine if it is
really a bug.
3. Finally, if the issue is not resolved by the above steps, open
an entry in the [SMTK Issue Tracker][].
[SMTK Issue Tracker]:
See [][] for instructions to contribute.
CMB is distributed under the OSI-approved BSD 3-clause License.
See [License.txt][] for details.
[License.txt]: LICENSE.txt
......@@ -165,7 +165,7 @@ pygments_style = 'sphinx'
findfigure_paths = {
os.path.join(sourcedir, 'userguide', 'figures'),
os.path.join(sourcedir, 'images', 'userguide', 'figures'),
SMTK Git Usage
SMTK version tracking and development is hosted by [Git](
Please select a task for further instructions:
Main Tasks
* [Install Git]( -
Git 1.7.2 or greater is preferred (required for development)
* [Download SMTK]( - Users start here
* [Develop SMTK]( - Contributors start here
Other Tasks
* [Review Changes]( -
SMTK GitLab Merge Requests
* [Learn Git]( -
Third-party documentation
The upstream SMTK repository has the following branches:
* `master`: Development (default)
* `hooks`: Local commit hooks
([placed]( in `.git/hooks`)
See [Labels]( for information on labels for Issues and Merge Requests.
# Simulation Modeling Tool Kit (SMTK)
## Version 1.0.0
[![Build Status](](
SMTK is a library which provides a way to specify attributes
(such as initial and boundary conditions, but also things
......@@ -20,9 +17,12 @@ What's below is a quick guide to building SMTK.
In order to build SMTK you must have
+ A modern C++ compiler (gcc, clang, or VS) that supports C++11 features,
+ [CMake]( 2.8.11 or newer (3.2 is advised), and
+ [Boost]( 1.60.0 or newer.
+ A modern C++ compiler that supports C++11 features
+ gcc 4.8 or newer
+ Xcode 7.1 or newer
+ Visual Studio 2013 64 bit or newer
+ [CMake]( 3.5 or newer
+ [Boost]( 1.60.0 or newer
We recommend using [Ninja]( for fast builds.
......@@ -31,9 +31,7 @@ You may optionally provide
+ [CGMA]( v13 or newer,
built with
[OpenCascade]( or
for importing CAD models;
[OpenCascade]( for importing CAD models;
+ [Python]( version 2.7.3 or newer and
[Shiboken]( from the smtk-head branch,
for Python wrappings of SMTK's C++ classes;
......@@ -64,7 +62,7 @@ If you want to build the documentation you will need
You may wish to obtain the test-data repository for SMTK in order
to run tests which require input datasets; run:
git clone
git clone
somewhere *outside* the SMTK source directory. When running CMake on SMTK,
set the `SMTK_DATA_DIR` variable to point to the directory `git clone`
This diff is collapsed.
Download SMTK with Git
This page documents how to download SMTK source code through [Git][].
See the [README]( for more information.
Optionally configure Git to [use SSH instead of HTTPS](#use-ssh-instead-of-https).
Clone SMTK using the commands:
$ git clone --recursive SMTK
$ cd SMTK
Users that have made no local changes and simply want to update a
clone with the latest changes may run:
$ git pull
$ git submodule update --init
Avoid making local changes unless you have read our [developer instructions][].
[developer instructions]:
Use SSH instead of HTTPS
Git can be configured to access ```` repositories through
the ``ssh`` protocol instead of ``https`` without having to manually change
every URL found in instructions, scripts, and submodule configurations.
1. Register for an account on [our GitLab instance][GitLab Access] and select a user name.
2. Add [SSH Keys][] to your GitLab account to authenticate your user via
the ``ssh`` protocol.
3. Configure Git to use ``ssh`` instead of ``https`` for all repositories
on ````:
$ git config --global url."".insteadOf
The ``--global`` option causes this configuration to be stored in
``~/.gitconfig`` instead of in any repository, so it will map URLs
for all repositories.
4. Return to the [Clone](#clone) step above and use the instructions as
written. There is no need to manually specify the ssh protocol when
cloning. The Git ``insteadOf`` configuration will map it for you.
[GitLab Access]:
[SSH Keys]:
[Labels][] are used to annotate [Issues][] and [Merge Requests][]. They help
organize and provide information about their state in the development
Labels are named using the form `[category]:[name]`. Labels in the same category
has the same color.
Labels in this category identify an aspect of SMTK affected by the issue.
Current list includes `area:build`, `area:doc`, `area:installing`,
and `area:testing`.
Reporters and developers can assign these labels to an issue to help organize.
An issue gets assigned a **Milestone** to indicate which release a fix for it
is planned for. The `priority:...` label can be used to indicate how critical is
this issue for that milestone.
| label | issues | merge requests | description |
| ----- | -------| -------------- | ----------- |
| `priority:required` | x | | issue is **required** for a milestone (highest priority) |
| `priority:important` | x | | issue is **important** for a milestone but may be okay if missed |
| `priority:nice-to-have` | x | | issue is **nice-to-have**, but not critical or important |
| `priority:low` | x | | low priority issues for a particular milestone |
If an issue targeted for a milestone has no priority label, then it is assumed
to be `priority:low`.
SMTK is composed of several different components. These labels are associated with Issues to identify the SMTK component associated with the issue. For example `component:attribute_system refers to SMTK's attribute system while component:gui would refers to SMTK's Qt GUI extensions.
These labels can be assigned to Issues and Merge Requests to help triage as
indicated in the table below:
| label | issues | merge requests | description |
| ----- | -------| -------------- | ----------- |
| `triage:confirmed` | x | | issue has been confirmed by someone other than the reporter |
| `triage:crash` | x | | issue describes condition causing a crash |
| `triage:easy` | x | | added by developers to issues that are easy to fix |
| `triage:expired` | x | x | added to issues closed without resolving or merge requests closed without merging due to lack of activity |
| `triage:feature` | x | | issue is a feature request; can be added by developers or reporters |
| `triage:incorrect-functionality` | x | | issue refers to unexpected behavior; can be added by developers or reporters |
| `triage:needinfo` | x | x | on an open issue, this label is added to indicate that more information is needed from the reporter; on a closed issue, this label is added to indicate that more information is needed from the developer who closed the issue about how to test or review the issue; on a merge request this label is added to request more information from the developer before the merge request can be reviewed |
| `triage:merge-needs-work` | | x | added to merge requests after review if the reviewer deems it needs more work before it can be merged |
| `triage:pending-dashboards` | | x | added to merge requests that are awaiting dashboards before they can be reviewed or merged |
| `triage:ready-for-review` | | x | added to merge requests that are ready for review by a developer |
These labels may be removed if the issue or merge request is no longer in the
state indicated by the label. For example, a merge request gets a `triage:ready-for-review`
label to request another developer to review it. If the reviewer deems it needs
more work, he should add the `triage:needswork` label and remove the `triage:ready-for-review`
label since the latter is no longer applicable.
These labels are added to issues to indicate their state in the development cycle.
Similar to `priority:...`, there can only be at most one workflow label on an issue
at a time.
| label | issues | merge requests | description |
| ----- | -------| -------------- | ----------- |
| `workflow:active-developement` | x | | added to an open issue that is under development |
| `workflow:customer-review` | x | | added to a closed issue that is ready for review by the customer/reporter |
[Merge Requests]:
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment