Skip to content

Commit 0e3e343

Browse files
shaswot77shaswot77
authored
Merge pull request #9 from squaredup/work/ss/contribution-guide
Plugins Contribution Guide
2 parents 00695dc + 3d20bc9 commit 0e3e343

4 files changed

Lines changed: 134 additions & 32 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Contributing to SquaredUp Community Plugins
2+
3+
First off, thanks for taking the time to contribute! :+1:
4+
5+
SquaredUp actively encourages external contributions so that the project can develop in such a way that benefits the wider SquaredUp community.
6+
7+
As a contributor, here are the guidelines we would like you to follow:
8+
9+
* [Code of Conduct](#coc)
10+
* [Question or Problem?](#question)
11+
* [Found a problem?](#problem)
12+
* [Suggest a feature?](#request)
13+
* [Contributing enhancements and plugins](#contribute)
14+
* [Submission Guidelines](#submit)
15+
16+
17+
## <a name="coc"></a> Code of Conduct
18+
19+
Help us keep SquaredUp Samples open and inclusive.
20+
Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
21+
22+
## <a name="question"></a> Got a question?
23+
24+
Please do not open issues for general support questions as we want to keep GitHub issues for bug reports and requests.
25+
26+
Please use [SquaredUp Community Answers](https://community.squaredup.com) to ask questions. The forums provide
27+
28+
* direct access to many people with extensive experience with SquaredUp
29+
* public viewing so your question and its answer can help someone else
30+
* central location where you and others can search for previously asked questions and answers
31+
32+
## <a name="problem"></a>Found a problem?
33+
If you find a bug or a problem, you can help us by:
34+
35+
* [Submit an support ticket](https://docs.squaredup.com/submit-ticket) with as much information as possible.
36+
* Even better, create a Pull Request with a fix!
37+
38+
## <a name="request"></a> Suggesting features and ideas
39+
Is there a plugin you need, but aren't able to develop? Does a plugin need an enhancement? Then [submit a feedback](https://feedback.squaredup.com/plugins), please provide lots of details to help us build it!
40+
41+
## <a name="contribute"></a>Contributing enhancements and plugins
42+
If there is an enhancement you want to make to an existing plugin or a cool new plugin you want to contribute then please submit a Pull Request with your work.
43+
44+
### <a name="submit"></a> Submitting a Pull Request (PR)
45+
Before you submit your Pull Request (PR) consider the following guidelines:
46+
47+
1. Search [GitHub](pulls) for an open or closed PR that relates to your submission. You don't want to duplicate effort.
48+
2. Read the [documentation](README.md) and explore the existing plugins for best practice guidance.
49+
3. For creating pull requests see - [Creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
50+
4. Make sure you pull request is appropriately described, and contains all the required files and documentation for review.
51+
52+
That's it, thank you for your contribution! :+1:

‎README.md‎

Lines changed: 55 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# SquaredUp Plugin Repository
1+
# SquaredUp Community Plugins Repository
22

3-
This repository contains third-party/community plugins for the SquaredUp Observability Portal product.
3+
This repository contains third-party/community plugins for [SquaredUp](https://squaredup.com).
44

55
## License
66

@@ -12,26 +12,19 @@ Please read and adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md) document b
1212

1313
## Introduction
1414

15-
This repository is a read-only copy of the documentation and test tools inside SquaredUp's main plugins repository. This contains the
16-
information you will need to understand the process involved in developing a plugin for the SquaredUp Observability Portal product.
17-
It contains tooling for you to make a start on developing a plugin. However, in order actually to install a plugin into the SquareUp
18-
product, you will need to engage with SquaredUp by emailing hello@squaredup.com.
15+
Plugins are vital components of SquaredUp. Each plugin bundles up everything involved in the interaction with a specific third party system, namely:
1916

20-
SquaredUp Cloud plugins are vital components of the SquaredUp Unified Observability Portal product. Each
21-
plugin bundles up everything involved in the interaction with a specific third party system, namely:
22-
23-
- The ability to import objects from an external system into the Observability Portal's Data Mesh.
17+
- The ability to import objects from an external system into SquaredUp.
2418
- The ability to read data upon demand from an external system for displaying in dashboards and/or for use in the evaluation of monitors.
2519

26-
Plugins are installed into the Observability Portal product as part of the product build process managed by SquaredUp. Once installed, they appear within the Data Source Gallery in the product:
20+
Plugins are installed into SquaredUp as part of the product build process. Once installed, they appear within the Data Source List in the product:
2721

28-
![DataSourceGallery](docs/images/DataSourceGallery.jpg)
22+
![DataSourceList](docs/images/DataSourceGallery.jpg)
2923

3024
## Execution Environments
3125

32-
A plugin may be executed in a cloud environment as part of the Observability Portal product or on a machine within a customer's premises (upon which the customer has installed a Relay Agent). If both environments are equally suitable for a plugin, it can
33-
be declared as "hybrid" (in which case, two separate plugins will appear in the Data Source Gallery, one with the suffix
34-
" On-Premise" automatically added).
26+
A plugin may be executed within SquaredUp's SaaS environment or on a machine within a customer's premises (upon which the customer has installed a Relay Agent). If both environments are equally suitable for a plugin, it can
27+
be declared as "hybrid" (in which case, two separate plugins will appear in the Data Source list, one with the label "On-Prem" added).
3528

3629
Javascript (NodeJS) is currently the implementation language/runtime with fullest capability, but PowerShell may be chosen for plugins which will only run On-Premise. We plan to support support other languages at some point in the future.
3730

@@ -46,22 +39,52 @@ A plugin is a directory in this repo of the form `plugins/`_plugin-name_`/v1` co
4639
- `metadata.json` - a file containing high-level information about the plugin (for example: the execution location of the plugin, or the information that appears in the Data Source Gallery, above).
4740
- `ui.json` - a file describing the configuration that must be shown to a user who is in the process of adding the plugin to their tenant to connect with an instance of the back end system.
4841
- `custom_types.json` (Optional) - a file containing information about non-standard object types that will be imported by the plugin into the Data Mesh.
49-
- `data_streams.json` - a file describing the streams of on demand data that the Observability Portal can request of the plugin.
42+
- `data_streams.json` - a file describing the streams of on demand data that SquaredUp can request of the plugin.
5043
- `handler.js` and `package.json` the executable code of the plugin.
5144

52-
## How to write a plugin
53-
54-
The suggested way to write a new plugin is to make a copy of the `examplePlugins/hybrid/v1` directory in your `plugins/`_plugin-name_`/v1` directory and then tailor the configuration and code to interact with the specific back end as required.
55-
56-
This process is described in more detail in [Writing a New Plugin](docs/writingANewPlugin.md).
57-
58-
## Testing your plugin
59-
60-
There are 2 main ways to test your plugin:
61-
62-
1. Using the SquaredUp Test/Validation Script (`validate.js` at the root of this repo)
63-
2. Testing within the SquaredUp Unified Observability Portal product. You would need to engage with SquaredUp to gain access to the private plugins repository before this means of testing is available to you. Contact hello@squaredup.com for more details.
64-
65-
You should aim to do as much testing as possible with the `validate.js` script as the turn-around time is much quicker.
66-
67-
This process is described in more detail in [Testing a Plugin](docs/testingAPlugin.md).
45+
## Writing a Plugin
46+
47+
1. **Clone the Repository:**
48+
First, clone the repository to your local machine:
49+
```bash
50+
git clone https://github.com/squaredup/squaredup-plugin-public.git
51+
cd squaredup-plugin-public
52+
```
53+
2. **Create a New Branch:**
54+
You will need to create a new branch for your changes:
55+
```bash
56+
git checkout -b add-new-plugin # Replace Branch Name
57+
```
58+
3. **Creating the Plugin Folder:**
59+
The suggested way to write a new plugin is to make a copy of the `examplePlugins/hybrid/v1` directory in your `plugins/`_plugin-name_`/v1` directory.
60+
```bash
61+
# Replace 'ExamplePlugin' with your plugin name
62+
mkdir -p 'plugins/ExamplePlugin/v1'
63+
cp -r 'examplePlugins/hybrid/v1/*' 'plugins/ExamplePlugin/v1/'
64+
```
65+
4. **Tailoring the Example Plugin:**
66+
You will need to tailor the configuration and code to interact with the specific back end as Required.
67+
This process is described in more detail in [Writing a New Plugin](docs/writingANewPlugin.md).
68+
5. **Testing the Plugin:** There are two main ways to test your plugin.
69+
1. Using the SquaredUp Test/Validation Script (`validate.js` at the root of this repo):
70+
```bash
71+
npm ci
72+
npm run validate
73+
```
74+
2. Using the SquaredUp Unit Test Framework which can be executed by running:
75+
```bash
76+
npm ci
77+
# Replace 'ExamplePlugin' with your plugin name
78+
npm test -- --pluginName="ExamplePlugin" --pluginPath="plugins/ExamplePlugin/v1"
79+
```
80+
You should aim to do as much testing as possible with the `validate.js` script as the turn-around time is much quicker.
81+
This process is described in more detail in [Testing a Plugin](docs/testingAPlugin.md).
82+
6. **Installation**
83+
The plugin is only installed when a Pull Request has been submitted. During PR creation you will be
84+
asked for your Tenant (Organization) Name which can be retrieved from the [settings page](https://app.squaredup.com/settings/organization).
85+
This will be used for restricting the plugin to the specified tenant only.
86+
Once the PR is approved and merged, the plugin will be available for everyone.
87+
88+
## Contributing
89+
90+
We greatly appreciate your interest in contributing to this repository! To help you get started, please take a look at our detailed contribution guidelines in the [CONTRIBUTING](CONTRIBUTING.md) document.

‎docs/images/DataSourceGallery.jpg‎

60.2 KB
Loading

‎resource.tf‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
terraform {
2+
required_providers {
3+
squaredup = {
4+
source = "registry.terraform.io/squaredup/squaredup"
5+
}
6+
}
7+
}
8+
provider "squaredup" {
9+
region = "us"
10+
api_key = "bIMYMcZJ9tlAFslAq0q0"
11+
}
12+
13+
resource "squaredup_workspace" "application_workspace" {
14+
display_name = "Application Team"
15+
description = "Workspace with Dashboards for Application Team"
16+
//auto link
17+
}
18+
19+
resource "squaredup_workspace" "devops_workspace" {
20+
display_name = "DevOps Team"
21+
description = "Workspace with Dashboards for DevOps Team"
22+
type = "application"
23+
tags = ["terraform", "auto-created"]
24+
workspaces_links = ["space-123"] //only link so disable auto link
25+
}
26+
27+
workspaces_links = [] #disable auto link

0 commit comments

Comments
 (0)