Skip to content

Commit fcf9221

Browse files
committed
Create an explanation for extensions registry
Looking to provide requirements and expectations for being listed in the registry. Signed-off-by: Paul Balogh <[email protected]>
1 parent 0f9645d commit fcf9221

File tree

2 files changed

+63
-2
lines changed

2 files changed

+63
-2
lines changed

src/data/markdown/docs/07 extensions/01 Get started/04 Create.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ there's some background knowledge you should have:
2525

2626
<Blockquote mod="note" title="">
2727

28-
If you maintain a public xk6 repository,
29-
the community appreciates that it stays up to date with the latest k6 APIs.
28+
If you maintain a public xk6 repository and wish to have your extension listed in our [registry](/extensions/get-started/explore/),
29+
be sure to review the [requirements](/extensions/explanations/about-the-extensions-registry#registry-requirements).
3030

3131
</Blockquote>
3232

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: About the Extensions Registry
3+
excerpt: Reasons for the registry and what is required to be included.
4+
hideFromSidebar: false
5+
---
6+
7+
Our desire is to provide the best developer experience when using k6.
8+
This extends to the extensions ecosystem as well.
9+
The adaptability provided by k6 extensions opens a wide-array of potential use cases.
10+
11+
The need for a well-maintained, curated listing of extensions is a necessity.
12+
Our pledge to the community will be to make our best attempt to ensure those projects listed meet certain standards.
13+
While we cannot guarantee the quality of community-provided extensions, we _can_ aid the evaluation by requiring certain consistencies.
14+
15+
Did you create an extension and want to share it with your fellow k6 users?
16+
We'd love to spread word of this new feature adding to our [registry](/extensions/get-started/explore/) of available extensions.
17+
18+
## Registry Requirements
19+
At a minimum, each source code repository should have the following:
20+
21+
- a README file containing project description, build and usage documentation, and version compatibilities
22+
- the `xk6` topic _(See the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics))_ for discoverability
23+
- a non-restrictive OSS license _(Apache2 preferred)_
24+
- an `examples` folder with at least one example to show proper usage
25+
- at least one [versioned release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)
26+
27+
In addition, extensions must successfully build with version(s) of k6 no older than one year and must specify the k6 versions it is compatible with.
28+
29+
<Blockquote mod="note" title="">
30+
31+
Our goal is to ease evaluation and adoption of extensions.
32+
33+
</Blockquote>
34+
35+
## Naming Conventions
36+
Some extensions may be very specific, where others are more general.
37+
Multiple extensions may even be created for the same product with different levels of support based upon version.
38+
By adhering to typical naming conventions, your extension name can remove some doubts as to what is supported.
39+
40+
For any extension we recommend the `xk6-` prefix as well as an optional `output-` for [Output extensions](/extensions/get-started/create/output-extensions/).
41+
Next, provide the product or protocol name; don't be cryptic.
42+
Ensure the usage is explicit by only adopting well-known acronyms or abbreviations if necessary.
43+
If your extension only supports a specific version of a product, incorporate the version into the name, for example `v2`.
44+
45+
As an example, suppose we've created an extension to output test metrics to the _AwesomeLog_ application strictly using the v2 API.
46+
In our case, let's say the latest v3 API is not backward-compatible.
47+
Applying our conventions, we'd recommend naming this repository as `xk6-output-awesomelog-v2`.
48+
49+
<Blockquote mod="note" title="">
50+
51+
Our goal is to quickly understand the intent of the extension.
52+
53+
</Blockquote>
54+
55+
## Potential for De-listing
56+
Given our desire to provide the best developer experience when using k6, we reserve the right to de-list any extension we deem is no longer maintaining standards.
57+
Before any action takes place, the extension maintainers will be contacted in attempt to rectify the project and thus avoid de-listing.
58+
Such contact may be in the form of GitHub issues or merge requests.
59+
60+
Should any extension be de-listed, this does not constitute a permanent removal.
61+
Any extension having been de-listed may be reinstated once the reasons for the initial removal have been remediated.

0 commit comments

Comments
 (0)