Add a guide to writing a composition function in Go #597

negz · 2023-11-01T00:16:43Z

Fixes #579

This is separate from the functions documentation under concepts because:

I expect to have similar guides for other languages, such as Python.
The guide will evolve outside of the Crossplane release cycle.

netlify · 2023-11-01T00:16:48Z

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	`5cda5e3`
🔍 Latest deploy log	https://app.netlify.com/sites/crossplane/deploys/65428f7b2c55190008310366
😎 Deploy Preview	https://deploy-preview-597--crossplane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: Accessibility: Best Practices: SEO: PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

negz · 2023-11-01T00:52:40Z

content/knowledge-base/guides/write-a-composition-function-in-go.md

+template Crossplane resources. Crossplane calls composition functions to
+determine what resources it should create when you create a composite resource
+(XR). Read the
+[concepts]({{<ref "../../master/concepts/composition-functions">}})


@plumbis I'd prefer to link to latest, or failing that v1.14 specifically.

I tried a regular [foo](/latest) style link, but HTML test didn't like it.

You can add docs.crossplane.io/latest/* to the htmltest config, since this is a deploy-time path.

docs/utils/htmltest/.htmltest.yml

Line 6 in 5dcc5b8

IgnoreURLs:

jbw976

leaving a partial review for now because the commits being pushed to this PR while i'm reviewing caused github to force me to refresh and I lose a comment or two i think - checkpointing to not lose anything else

content/knowledge-base/guides/write-a-composition-function-in-go.md

jbw976

This is basically great @negz!!! a few questions, improvements, and some odd renderings, but basically resolve these as you see fit and ship it!!

content/knowledge-base/guides/write-a-composition-function-in-go.md

Remove the big example, there's now something better in the docs. The linked guide won't exist until the below PR is merged. crossplane/docs#597 Signed-off-by: Nic Cope <[email protected]>

ezgidemirel

Thanks @negz for the guide, it looks great! I have two things to add:

I believe it's worth mentioning that functions need to be idempotent. It's an easy mistake to forget that (especially for an operation like create) and act like they're running only once.
We may add an examples folder to the function template and encourage function authors to add examples. Later, we can display them in the marketplace, just like we do with providers.

negz · 2023-11-01T16:47:17Z

We may add an examples folder to the function template and encourage function authors to add examples. Later, we can display them in the marketplace, just like we do with providers.

@ezgidemirel I coincidentally actually did that last night - https://github.com/crossplane/function-template-go. 😄

plumbis

I think there is something wacky with how vale is building tokens from words and parsing. Testing locally adding the ticks around function-template-go on line 434 and xpkg.upbound.io on line 482 made the other spelling errors go away.

Can you try making those changes and see if vale stops grumping?

content/knowledge-base/guides/write-a-composition-function-in-go.md

This is separate from the functions documentation under concepts because: 1. I expect to have similar guides for other languages, such as Python. 2. The guide will evolve outside of the Crossplane release cycle. Signed-off-by: Nic Cope <[email protected]>

Signed-off-by: Nic Cope <[email protected]>

Vale considers it a spelling mistake, and it's easy to rephrase around. Signed-off-by: Nic Cope <[email protected]>

We don't have any docs specific to multi-platform _packages_ AFAIK. Signed-off-by: Nic Cope <[email protected]>

Signed-off-by: Nic Cope <[email protected]>

To workaround spellchecker thinking "Go." (with period) is a spelling mistake. Signed-off-by: Nic Cope <[email protected]>

I do actually want latest, but HTML test complains when I try. There's no v1.14 release directory to link to yet, so master will have to do. Signed-off-by: Nic Cope <[email protected]>

Signed-off-by: Nic Cope <[email protected]>

negz · 2023-11-01T17:24:02Z

Can you try making those changes and see if vale stops grumping?

@plumbis It worked, thank you!

negz · 2023-11-01T17:25:00Z

I believe it's worth mentioning that functions need to be idempotent. It's an easy mistake to forget that (especially for an operation like create) and act like they're running only once.

@ezgidemirel Agreed - I'll do a pass to make sure this is really clear. I'd like to get this merged as-is though since we shipped today. Will do that in a follow-up.

This seems like the most future-proof option for this guide, which lives outside of any version. Signed-off-by: Nic Cope <[email protected]>

negz requested review from plumbis, jbw976 and ezgidemirel November 1, 2023 00:37

negz force-pushed the get-func-ey branch from c9586c9 to f0cd431 Compare November 1, 2023 00:47

negz commented Nov 1, 2023

View reviewed changes

jbw976 reviewed Nov 1, 2023

View reviewed changes

negz force-pushed the get-func-ey branch from 27ce54b to e73d32f Compare November 1, 2023 00:59

negz commented Nov 1, 2023

View reviewed changes

content/knowledge-base/guides/write-a-composition-function-in-go.md Show resolved Hide resolved

negz commented Nov 1, 2023

View reviewed changes

content/knowledge-base/guides/write-a-composition-function-in-go.md Show resolved Hide resolved

jbw976 approved these changes Nov 1, 2023

View reviewed changes

negz mentioned this pull request Nov 1, 2023

Link to documentation in README crossplane/function-sdk-go#74

Merged

2 tasks

ezgidemirel approved these changes Nov 1, 2023

View reviewed changes

plumbis reviewed Nov 1, 2023

View reviewed changes

content/knowledge-base/guides/write-a-composition-function-in-go.md Outdated Show resolved Hide resolved

content/knowledge-base/guides/write-a-composition-function-in-go.md Outdated Show resolved Hide resolved

negz added 13 commits November 1, 2023 10:22

It's function-xbuckets plural, not xbucket

9f11057

Signed-off-by: Nic Cope <[email protected]>

Avoid saying "Crossplane CLI's"

056c350

Vale considers it a spelling mistake, and it's easy to rephrase around. Signed-off-by: Nic Cope <[email protected]>

Link to Docker docs on multi-platform images

2343b67

We don't have any docs specific to multi-platform _packages_ AFAIK. Signed-off-by: Nic Cope <[email protected]>

Add multi-platform as allowed jargon

698306f

Signed-off-by: Nic Cope <[email protected]>

Link to go.dev

a1542b2

To workaround spellchecker thinking "Go." (with period) is a spelling mistake. Signed-off-by: Nic Cope <[email protected]>

Update all links to point to master, not latest

6487b23

I do actually want latest, but HTML test complains when I try. There's no v1.14 release directory to link to yet, so master will have to do. Signed-off-by: Nic Cope <[email protected]>

Attempt to workaround various "spelling mistakes"

038ad6b

Signed-off-by: Nic Cope <[email protected]>

Don't perma-disable the future tense linter

fde689d

Signed-off-by: Nic Cope <[email protected]>

Clarify that not all functions should delete the input directory

47e6e77

Signed-off-by: Nic Cope <[email protected]>

Add MORE BRACES to packages documentation link

2d3082f

Signed-off-by: Nic Cope <[email protected]>

Remove extraneous period.

06d7247

Signed-off-by: Nic Cope <[email protected]>

Fix sneaky Vale spelling errors

acf6be5

Signed-off-by: Nic Cope <[email protected]>

negz force-pushed the get-func-ey branch from b64ed9b to acf6be5 Compare November 1, 2023 17:22

Link to latest docs

5cda5e3

This seems like the most future-proof option for this guide, which lives outside of any version. Signed-off-by: Nic Cope <[email protected]>

negz force-pushed the get-func-ey branch from 66fe310 to 5cda5e3 Compare November 1, 2023 17:48

negz merged commit 68a8cd9 into crossplane:master Nov 1, 2023
6 checks passed

negz deleted the get-func-ey branch November 1, 2023 17:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a guide to writing a composition function in Go #597

Add a guide to writing a composition function in Go #597

negz commented Nov 1, 2023

netlify bot commented Nov 1, 2023 •

edited

Loading

negz Nov 1, 2023

plumbis Nov 1, 2023

jbw976 left a comment

jbw976 left a comment

ezgidemirel left a comment

negz commented Nov 1, 2023

plumbis left a comment

negz commented Nov 1, 2023

negz commented Nov 1, 2023

Add a guide to writing a composition function in Go #597

Add a guide to writing a composition function in Go #597

Conversation

negz commented Nov 1, 2023

netlify bot commented Nov 1, 2023 • edited Loading

✅ Deploy Preview for crossplane ready!

negz Nov 1, 2023

Choose a reason for hiding this comment

plumbis Nov 1, 2023

Choose a reason for hiding this comment

jbw976 left a comment

Choose a reason for hiding this comment

jbw976 left a comment

Choose a reason for hiding this comment

ezgidemirel left a comment

Choose a reason for hiding this comment

negz commented Nov 1, 2023

plumbis left a comment

Choose a reason for hiding this comment

negz commented Nov 1, 2023

negz commented Nov 1, 2023

netlify bot commented Nov 1, 2023 •

edited

Loading