User Documentation
This is the user documentation of the Gropius Visual Studio Code extension. To begin using the extension, first configure your workspace mapping by following the instructions in the Mapping Folders to Component Versions section, which will connect your local workspace to the Gropius components and enable all cross-component issue management features.
Gropius is a cross-component issue management system, which has been created to address the challenges of managing issues across interconnected components in modern software architectures, particularly microservices and component-based systems. Traditional issue management systems (IMSs) focus primarily on single-component problems and lack awareness of the architectural dependencies that can cause issues to propagate across different parts of a system. Gropius aims to fill this gap by providing a system capable of handling cross-component issues. The concept behind Gropius has been explained in detail in this paper, and its respective Git repository can be found here.
The Gropius Visual Studio Code extension has been created in order to seamlessly integrate cross-component issue management into the developer workflow by bringing Gropius functionalities directly into Visual Studio Code. Because of this reason, the extension extends the Gropius application, thus introducing the already existing Gropius functionality inside a well-known IDE. Simply said, the goal is to aid developers by removing the need of constantly switching between coding environment and browser.
In this section, we go through all the parts that make up the VS Code extension. For each view and its individual functionality blocks, we explain their purpose and how to use them, including images to make the explanations clearer. The extension consists of the following views: component versions view, component issues view and issue details view. It also includes a workspace graph and an issue graph.
📚 Click to expand Navigation Links
Gropius targets developers working on several components (with issues propagating in-between those components) at the same time. A handy functionality of Visual Studio Code is that developers can create and work inside workspaces. A workspace consists of one or more root folders, e.g., each of them implementing a different component of a system. This in turn defines the most important use-case for the Gropius extension — concurrent work on different components (opened inside the same workspace) and management of the issues that propagate between those components. Here, it is important to note that not all components necessarily originate from the same project.
The first step is to define our workspace, import the projects and components that we plan to work on and then map them to the corresponding component versions.
E.g., we can first add an initial folder (of a component) with which we can initiate our workspace.
Then, we can add additional folders to our workspace.
The Gropius extension requires a mapping configuration for each workspace root folder to connect your local development environment with the Gropius issue management system. This mapping establishes which folders in your workspace correspond to which component versions in Gropius.
For each workspace root folder, you need to create a .gropius.yaml configuration file at the root of that folder. This file defines how folders within that workspace root map to Gropius components and component versions. The mapping does not need to cover every folder in your workspace (partial mapping is allowed - some root folders can be unmapped). Mappings must not overlap to prevent ambiguity.
Example of a root folder structure including the .gropius.yaml configuration file:
Two Options for Mapping Components: You have two different ways to map your folders to component versions:
- Option 1: Direct Component Version Mapping: Map a folder directly to a specific component version using its component version ID. This is the most precise mapping option as it targets an exact version.
.gropius.yaml using direct component version mapping:
mappings:
- path: "/"
componentVersion: "component-version-id" # ID of the specific component version
This maps the entire root folder to a specific component version.
You can also map specific subfolders:
mappings:
- path: "/src"
componentVersion: "component-version-id-1" # ID of Component A Version 1.0
- path: "/docs"
componentVersion: "component-version-id-2" # ID of Documentation Component Version 2.3
- Option 2: ComponentID + ProjectID Mapping: Map a folder to a component ID combined with a project ID. This automatically resolves to ALL component versions in the specified project that match the component. This is useful when you want to work with all versions of a component within a specific project.
Example .gropius.yaml using component + project mapping:
mappings:
- path: "/frontend"
project: "project-id" # ID of your project
component: "component-id" # ID of frontend component that has multiple versions in this project
- path: "/backend"
project: "project-id" # Same or different project ID
component: "component-id" # ID of backend component
If a root folder doesn't correspond to any Gropius component version, you can still create an empty mapping file:
mappings: [] # empty, since no component version corresponds to anything in this root folder
In Gropius we do not only work with components, but also with component versions. Inside the Component Versions View, we see a structure that lists all mapped folders currently opened in our workspace, the components affected by those repositories, and the component versions worked upon.
E.g., we have a component called Order Management Service. When we hover over it, we can see its description. We can also see that there is only one version of it affected by the corresponding folder, and that is v2. But since we work inside a workspace that consists of multiple root folders, we can also see the same component listed under the folder multi-component-root. There, the code opened affects two versions of the service, those being v1 and v2.
Gropius manages cross-component issues, so when clicking on a component or a component version, one can see all relevant issues in the following view.
In this view, all issues related to a given component or component version are listed. When selecting in the Component Versions View, your selection affects which issues are displayed:
- Clicking on a component name is the same as selecting the first version tag: all issues related to that component are shown.
- Clicking on any specific version tag also shows all component issues initially.
- To see only issues affecting a particular version, use the "V" filter button in the filter toolbar - this version filter narrows the list to show only issues that affect the specifically selected component version.
This filtering mechanism allows you to toggle between viewing all component issues and just those affecting a specific version. The search bar allows us to search for a specific issue.
Multiple filtering options exist. One can look for issues depending on their status (e.g., Open) or their type (e.g., Bug). The issues can also be ordered alphabetically. The icon shown for each issue in the list of issues signals about the status and type, as well as whether it has incoming or outgoing relations.
New issues can be created as shown in the following image. In the first tab, one can define the title, template, type, and state of an issue. Required fields are indicated.
In the second tab, one can write the issue's description. The description can be written in Markdown format, allowing highlighting and structuring information more easily. There is also an option to preview how the description would look when processed.
In the third tab, values for the templated fields can be filled in - what is to be filled in depends on the issue template. In the following example the estimated effort can be selected.
Having created the issue, we can now view it in the list of issues. Keep in mind that the issue is created for the component currently selected in the Component Versions View. If you have selected a version, the issue will be created for the corresponding component. In our ongoing example, this would be the Order Management Service.
After clicking on an issue from the list of issues, we can open its respective Issue Details View.
In this view, we can see all information relevant for the given issue, but also edit it. In this example, we will look at an issue called Load Balancing and Horizontal Scaling.
The title of the issue can be edited.
The relevant page of the issue can be opened in the Gropius browser application.
We can edit the type of the issue.
We can also edit the state of the issue. The state is represented by a color:
- Green for Open,
- Red for Not Planned or Completed, etc.
Additionally, we can set the priority of the issue. Currently, it is set to High.
In this section, we handle functionality related to labels:
You can edit and remove labels.
Currently, Load Balancing and Horizontal Scaling has the labels pretty hard and 2 people needed.
You can also search for and add new labels.
Additionally, you can create new labels — set a title, description, and color.
We can also see all entities affected by the issue. In our ongoing example, Load Balancing and Horizontal Scaling affects the project Package Delivery System, as well as several component versions.
Affected entities can also be removed for the issue through the extension.
Furthermore, new affected entities can be added.
You can specify or edit the description of an issue.
When editing, the description is loaded in a larger window on the right, which allows you to use the Preview support by VSCode.
You can view all comments related to the issue - date of creation and user are also displayed. A comment can be edited and deleted and new comments can be created similarly to the way the description can be edited.
One can view and edit all related issues: An issue can have outgoing relations (defined here) and incoming relations (defined by other issues).
Editing outgoing relations is possible — including changing relation types or removing/adding relations:
Adding new outgoing relations:
You can view who is assigned to the issue. New assignments can be created, current assignments can be deleted. You can search for users in a search field and you can change the type of assignment. The list of types in the dropdown depends on the assignment template.
Artifacts in Gropius are segments of code that are affected by or related to issues. A single piece of code can be associated with multiple issues, providing traceability between code and the issues that affect it.
Visual Indicators
- Open issues' artifacts are always highlighted with an icon in the editor, regardless of whether the issue is currently selected in the extension
- For issues in other states (e.g., completed, closed), artifacts are only highlighted when the corresponding issue is opened in the Issue Details view
- The highlighting is done using the issue icon for the first and the last line of the code block. If a line is highlighted more than once, a number appears next to it indicating the number of relevant artifacts.
Viewing Issue Details from Artifacts
To quickly view an issue associated with a code artifact, right-click on any line that has an artifact indicator (gutter icon) and select "View Associated Issues" from the context menu. This will open the issue in the Issue Details view.
If multiple issues are associated with the same line of code, a selection menu will appear allowing you to choose which issue to view.
To create an artifact directly for the currently selected issue:
- Open the corresponding file in the editor
- Select the relevant code with your mouse
- Click the "Create" button in the issue's Artifact section
- You'll be prompted to select:
- The trackable entity (project or component) that the artifact is related to
- The artifact template
- Optionally, to write a description for the artifact
Note: If you're not prompted for one of these options, it means there's only one possible choice available. Once everything is selected, the artifact will be created for the issue that's currently open in the Issue Details view.
You can also create artifacts that aren't initially attached to any issue:
- Open the file in the editor
- Select the relevant code with your mouse
- Right-click and select "Create Standalone Artifact"
- You'll be prompted for the same information as when creating artifacts for an issue
These standalone artifacts can later be added to issues as needed.
You can add existing artifacts to an issue through the Issue Details view: In the Artifacts section, click the "Add" button. Only relevant artifacts will be shown in the selection list - those with trackable components that the issue affects. Relevant standalone artifacts will also appear in this list. Select the artifact(s) you want to add.
To remove an artifact from an issue: In the Issue Details view, find the artifact in the Artifacts section and xlick the "X" button next to the artifact. **Important: **This action only removes the association between the artifact and the issue - it does not delete the artifact itself. The artifact can be added again later if needed. To permanently delete an artifact, you must use the Gropius browser interface.
These are customizable fields that depend on the issue template and define additional information for an issue. An example is Estimated Effort - in the previous example, where an issue was created, we selected the value of the templated field Estimated Effort.
While in the Browser UI we have a graph for a project, the extension allows visualizing a graph for a workspace and a graph for an issue and using interactive graphs.
Workspace Graph: displays all Gropius component versions that exist within your VSCode workspace. The workspace graph can be accessed via a button in the Component Versions View, allowing you to visualize the architectural landscape of your entire workspace at once.
Issue Graph: shows the relationships between the current issue and other connected entities in the Gropius system. The issue graph can be accessed through a button in the Issue Details View.
Both graphs offer interactive functionality, allowing you to explore relationships, zoom in and out, and better understand the connections within your system.
Thank you for using the Gropius Visual Studio Code Extension! 🚀 We hope this tool helps make your cross-component issue management easier, faster, and more efficient. For feedback, questions, or contributions, feel free to reach out via Gropius GitHub or open an issue in the extension repository.
Happy coding! 👩💻👨💻