Add initial xk6 documentation #346

imiric · 2021-06-30T10:01:45Z

Closes #169

mstoykov · 2021-06-30T10:04:48Z

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

+  [`context.Context`](https://golang.org/pkg/context/#Context) instance as the first argument.
+  This context is used throughout the k6 codebase and contains embedded objects
+  which can be extracted to access the
+  [`goja.Runtime`](https://pkg.go.dev/github.com/dop251/goja#Runtime) for a
+  particular VU, and to get more information about the test in progress.
+  Take a look at
+  [`common.GetRuntime()`](https://pkg.go.dev/go.k6.io/[email protected]/js/common#GetRuntime),
+  [`lib.GetState()`](https://pkg.go.dev/go.k6.io/[email protected]/lib#GetState) and
+  [`lib.GetExecutionState()`](https://pkg.go.dev/go.k6.io/[email protected]/lib#GetExecutionState).


This might drastically change depending on the changes around grafana/k6#1802, so maybe we should first decide on whether we will do any of the changes proposed there before we document stuff we might break

Good point, but that will change in v0.34.0, right? Since we have versioned docs now, I think it's fine to mention the current API here.

EDIT: Actually, only JS API docs are versioned, so guess not 😞

github-actions · 2021-06-30T10:17:35Z

There's a version of the docs published here:

https://mdr-ci.staging.k6.io/docs/refs/pull/346/merge

It will be deleted automatically in 30 days.

ppcano · 2021-07-01T05:53:49Z

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

+---
+
+Traditionally, extending k6 with custom functionality that isn't available in the


In Docs, I'd remove the whole historical intro.

Additionally, I would add a label about version support like in Scenarios.

Hhmm I think explaining the issues extensions were meant to solve serves as a good introduction for why someone might want to use them. Starting from "What are k6 extensions?" would be too abrupt IMO. Unless you have another suggestion for the intro :)

And sure, I'll add a more prominent version support notice.

Added the version support notice in a89ceda.

Let me know about the intro.

https://github.com/grafana/k6-docs/pull/346/files#r678100601

ppcano · 2021-07-01T06:00:40Z

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

+
+k6 extensions are standalone Go projects that call k6 APIs but are otherwise
+unrestricted in their functionality. This provides the freedom for extension authors


In the beginning, we should focus on describing the benefits of this feature.

Having the ability to experiment with extensions that can become part of the feature is a "secondary" benefit, at least for the end user, imho.

This is mostly a definition paragraph, but what other benefits would you mention?

The historical introduction explains the issues extensions are meant to solve for end users, so I'm not sure what else to mention here.

Also about https://github.com/grafana/k6-docs/pull/346/files#r661994675

My view here is that the intro and the what is k6 extension and what is xk6 sections are a little verbose. For the Intro sections, I rather going more direct to the point in Docs and extend the historical in the blog post.

I like Extension Types section, but perhaps the Getting Started section could be better connected with the intro.

The article is very good. If you want, I can give it a try in the future for a new proposal of the intro.

ppcano · 2021-07-01T06:07:39Z

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

+  that output implementations can use which handles bufferring and periodic
+  flushing in a thread-safe way.
+  For usage examples see the [`statsd` output](https://github.com/k6io/k6/blob/v0.33.0/output/statsd/output.go#L55).


Can you add an example of an extension instead of the k6 codebase?

Hhmm we already have a lot of external examples and I thought it would be good to link to an internal module for once, to showcase that extensions and internal modules are near identical in implementation.

Besides, I'm not sure there are any extensions that actually use this yet, since it hasn't been documented ;)

ppcano · 2021-07-01T06:10:28Z

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

+
+A few things to keep in mind when writing a new extension:
+<!-- TODO: Better structure this list? -->


Agree. It is a bit hard to follow.

I wonder if. it could be good to show snippets of relevant extension code to distinguish between the various sections and make the whole section more pleasant to read.

Yeah, could be... In #169 we kind of agreed to not show any Go code here, but we could split this section into "Writing a new JS extension" (linking to the existing article) and "Writing a new Output extension", and do a small walkthrough with some snippets of code instead of a complete extension like in the article.

I'll think about it, and more opinions are welcome. :)

@ppcano Take a look at the latest changes. It kind of breaks the no-code rule, but I really don't think we can document writing an extension without showing code... :)

ppcano · 2021-07-01T06:13:44Z

It's a good start @imiric. I have added a few comments about the first impressions, take the feedback as suggestions or to think about.

simskij · 2021-07-20T12:39:38Z

What's the status here, @imiric and @ppcano? Is this abandoned, finished, or still ongoing?

imiric · 2021-07-20T12:55:35Z

@simskij It's in progress and awaiting more feedback. I actually picked it back up today to address this and this, but new comments are welcome.

Maybe resolves #346 (comment) ? Still needs a bit of work.

imiric · 2021-07-23T15:23:26Z

I expanded more on the writing extension part, but it will need fact checking from @na-- and @mstoykov 😅

It's still a bit WIP and there are some TODOs and ellipsis that should be addressed, but there shouldn't be much left after that.

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

Resolves #346 (comment)

imiric · 2021-07-27T15:46:41Z

This is ready for review again. @na-- @mstoykov @ppcano 🙏

@simskij I mentioned the supported modes of execution in 56b3702, but can you clarify what you meant by "considerations and drawbacks"? I'm not sure what else to mention besides whether custom k6 binaries are supported or not. Suggestions welcome :)

imiric · 2021-07-27T15:48:24Z

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

+is on our roadmap. However, it is possible to run a binary built with xk6 and send
+metrics produced by extension code to the Cloud using the
+[`cloud` output](https://k6.io/docs/results-visualization/cloud/).


Should we add some kind of outro here, relevant links, etc.?

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md

Resolves #346 (comment)

#346 (comment)

Resolves #346 (comment)

Resolves: - #346 (comment) - #346 (comment)

This briefly mentions common.Bind() and shows a more advanced module example using the new IsModuleV2 approach. Should resolve #346 (comment)

Resolves #346 (comment)

Partly resolves https://github.com/grafana/k6-docs/pull/346/files#r661994675

#346 (comment)

Resolves #346 (comment)

Resolves: - #346 (comment) - #346 (comment)

This briefly mentions common.Bind() and shows a more advanced module example using the new IsModuleV2 approach. Should resolve #346 (comment)

Resolves #346 (comment)

ppcano · 2021-10-14T09:47:05Z

@na-- @mstoykov Any blocker here? I suggest merging it and iterating it next. We want to migrate this content to the Extensions section and will require some minor changes later.

codebien · 2021-10-14T17:19:16Z

@imiric Does xk6 support the vendor folder? If not, should we mention something about it?

Resolves #346 (comment)

imiric · 2021-10-15T08:01:02Z

@codebien It doesn't and good idea. I mentioned it in db1c351.

na--

LGTM, we'd just need to update some things when v0.35.0 is released. @ppcano, feel free to merge this

imiric requested review from mstoykov, ppcano, simskij, codebien and na-- June 30, 2021 10:01

mstoykov reviewed Jun 30, 2021

View reviewed changes

ppcano reviewed Jul 1, 2021

View reviewed changes

imiric pushed a commit that referenced this pull request Jul 23, 2021

WIP Add JS and Output sections

d740d18

Maybe resolves #346 (comment) ? Still needs a bit of work.

imiric force-pushed the docs/xk6 branch from 8269b2c to d740d18 Compare July 23, 2021 15:15

imiric requested review from mstoykov and ppcano July 23, 2021 15:19

imiric commented Jul 23, 2021

View reviewed changes

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md Outdated Show resolved Hide resolved

imiric commented Jul 27, 2021

View reviewed changes

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md Outdated Show resolved Hide resolved

imiric pushed a commit that referenced this pull request Jul 27, 2021

Add JS and Output sections

73ab891

Resolves #346 (comment)

imiric force-pushed the docs/xk6 branch from a89ceda to 56b3702 Compare July 27, 2021 15:40

imiric commented Jul 27, 2021

View reviewed changes

mstoykov reviewed Jul 27, 2021

View reviewed changes

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md Outdated Show resolved Hide resolved

ppcano reviewed Jul 28, 2021

View reviewed changes

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md Outdated Show resolved Hide resolved

ppcano reviewed Jul 28, 2021

View reviewed changes

src/data/markdown/translated-guides/en/07 Misc/05 k6 Extensions.md Outdated Show resolved Hide resolved

imiric pushed a commit that referenced this pull request Sep 29, 2021

Add JS and Output sections

593fd38

Resolves #346 (comment)

imiric force-pushed the docs/xk6 branch from 56b3702 to cea0b37 Compare September 29, 2021 09:32

imiric pushed a commit that referenced this pull request Oct 8, 2021

Replace GitHub code links with pkg.go.dev

95db500

#346 (comment)

imiric pushed a commit that referenced this pull request Oct 8, 2021

Suggest implementing a JS library instead of an extension

b64bc4b

Resolves #346 (comment)

imiric pushed a commit that referenced this pull request Oct 8, 2021

Don't mention release versions again

fa410c7

Resolves: - #346 (comment) - #346 (comment)

imiric pushed a commit that referenced this pull request Oct 8, 2021

Add advanced JS module example

7638bdd

This briefly mentions common.Bind() and shows a more advanced module example using the new IsModuleV2 approach. Should resolve #346 (comment)

imiric pushed a commit that referenced this pull request Oct 8, 2021

Fix exports in advanced JS module example

6ffcc1f

Resolves #346 (comment)

imiric pushed a commit that referenced this pull request Oct 8, 2021

Fix rendering of inline Go struct tag example

6cb9622

Resolves #346 (comment)

imiric pushed a commit that referenced this pull request Oct 8, 2021

Remove k6 version from pkg.go.dev links

0c2d3e8

Resolves #346 (comment)

imiric force-pushed the docs/xk6 branch from 3bd78b8 to 0c2d3e8 Compare October 8, 2021 12:50

codebien approved these changes Oct 8, 2021

View reviewed changes

Ivan Mirić added 13 commits October 11, 2021 10:25

Add xk6 documentation

78f600c

Add JS and Output sections

8854c23

Resolves #346 (comment)

Add version support notice to xk6 docs

f720950

Partly resolves https://github.com/grafana/k6-docs/pull/346/files#r661994675

Mention supported modes of execution

75d9547

Replace GitHub code links with pkg.go.dev

5fe9242

#346 (comment)

Suggest implementing a JS library instead of an extension

461cba1

Resolves #346 (comment)

Don't mention release versions again

3311325

Resolves: - #346 (comment) - #346 (comment)

Address comments by codebien

9dbf5ca

Add advanced JS module example

141057f

This briefly mentions common.Bind() and shows a more advanced module example using the new IsModuleV2 approach. Should resolve #346 (comment)

Fix exports in advanced JS module example

402a039

Resolves #346 (comment)

Fix typo

c867009

Fix rendering of inline Go struct tag example

4b940cc

Resolves #346 (comment)

Remove k6 version from pkg.go.dev links

3116418

Resolves #346 (comment)

imiric force-pushed the docs/xk6 branch from 0c2d3e8 to 3116418 Compare October 11, 2021 08:49

Add note about vendored dependencies

db1c351

Resolves #346 (comment)

na-- approved these changes Oct 19, 2021

View reviewed changes

ppcano merged commit 2fb24f4 into main Oct 19, 2021

na-- deleted the docs/xk6 branch October 19, 2021 10:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add initial xk6 documentation #346

Add initial xk6 documentation #346

imiric commented Jun 30, 2021 •

edited

Loading

mstoykov Jun 30, 2021

imiric Jun 30, 2021 •

edited

Loading

github-actions bot commented Jun 30, 2021

ppcano Jul 1, 2021

imiric Jul 1, 2021

imiric Jul 26, 2021

ppcano Jul 28, 2021

ppcano Jul 1, 2021 •

edited

Loading

imiric Jul 1, 2021

ppcano Jul 28, 2021 •

edited

Loading

ppcano Jul 1, 2021

imiric Jul 1, 2021

ppcano Jul 1, 2021

imiric Jul 1, 2021

imiric Jul 23, 2021

ppcano commented Jul 1, 2021

simskij commented Jul 20, 2021

imiric commented Jul 20, 2021

imiric commented Jul 23, 2021

imiric commented Jul 27, 2021

imiric Jul 27, 2021

ppcano commented Oct 14, 2021 •

edited

Loading

codebien commented Oct 14, 2021

imiric commented Oct 15, 2021

na-- left a comment

		---

		Traditionally, extending k6 with custom functionality that isn't available in the


		k6 extensions are standalone Go projects that call k6 APIs but are otherwise
		unrestricted in their functionality. This provides the freedom for extension authors


		A few things to keep in mind when writing a new extension:
		<!-- TODO: Better structure this list? -->

Add initial xk6 documentation #346

Add initial xk6 documentation #346

Conversation

imiric commented Jun 30, 2021 • edited Loading

Choose a reason for hiding this comment

imiric Jun 30, 2021 • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Jun 30, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ppcano Jul 1, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ppcano Jul 28, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ppcano commented Jul 1, 2021

simskij commented Jul 20, 2021

imiric commented Jul 20, 2021

imiric commented Jul 23, 2021

imiric commented Jul 27, 2021

Choose a reason for hiding this comment

ppcano commented Oct 14, 2021 • edited Loading

codebien commented Oct 14, 2021

imiric commented Oct 15, 2021

na-- left a comment

Choose a reason for hiding this comment

imiric commented Jun 30, 2021 •

edited

Loading

imiric Jun 30, 2021 •

edited

Loading

ppcano Jul 1, 2021 •

edited

Loading

ppcano Jul 28, 2021 •

edited

Loading

ppcano commented Oct 14, 2021 •

edited

Loading