Refresh the provider development guide

[negz]

What problem are you facing?

We've tried to make contributing a managed resource to a Crossplane provider easier than writing an arbitrary Kubernetes controller from scratch, but it's still a fairly complex task. In Crossplane implementing a managed resource typically boils down to defining the API type (using kubebuilder and controller-tools) then implementing an ExternalClient. During code review we find folks often have trouble with the following areas:

• 'Interpreting' external APIs - i.e. representing them as Kubernetes CRs. Some external APIs are more imperative than declarative, and don't map cleanly.
• Writing idiomatic API types - things like optional fields being pointers, what goes in spec and status, etc.
• Implementing IsUpToDate checks that determine whether an external resource needs updating.

We do already have several resources to help with this, e.g.:

• https://github.com/crossplane/crossplane/blob/v1.3.0/design/one-pager-managed-resource-api-design.md
• https://github.com/crossplane/crossplane/blob/v1.3.0/CONTRIBUTING.md
• https://crossplane.io/docs/v1.3/contributing/provider_development_guide.html
• https://github.com/crossplane/provider-template/
• https://github.com/crossplane/provider-aws/blob/master/CODE_GENERATION.md

Unfortunately these documents don't form a particularly cohesive guide, and are in some cases (particularly the developer guide) somewhat out of date.

How could Crossplane help solve your problem?

I think it would be worth someone taking a pass over these documents and 'refreshing' them. I'm not exactly sure how this would look, but I have a hunch that making sure the provider development has no outdated or misleading information would go a long way. I'd also consider trying to roll some of the information from the managed resource API design document into the guide so that folks had the majority of the information they needed in one place.

[negz]

Cross-linking #2258.

[Feggah]

Here at @stone-payments we created an internal wrapped up documentation for the company about developing managed resources. We saw that the needed information to do it was spread across multiple crossplane docs (TBS videos, official crossplane docs, etc) so we decided to create one wrapping up it all.

The real "problem" is that this docs are in Portuguese, so we would need to translate it to give it to the community. Do you think that this can help Crossplane?

[negz]

@Feggah! I do - I could imagine even the original Portuguese version being useful to us though to be fair we have no experience maintaining documentation in languages other than English at this stage.

[Feggah]

Nice @negz! So I'll arrange things internally and try to spend some time in this translation. I think it is one of the firsts documentations in Portuguese about Crossplane, but we are by no means crossplane-experts, so I'm thinking that the best we can do here is translate the docs, get reviews on it, improve/fix things that aren't correct, and give it to the community.

We can fix the Portuguese version with the same fixes that we will need to apply in the English one, so both docs will be up to date and correct. If you want to have the Portuguese version as well in Crossplane docs, I help you with maintaining it.

[negz]

Adding a note that per @chlunde's suggestion, when we put this together we may also want to consider whether there is any help we could condense for folks reviewing new managed resource contributions.

[erikgb]

I could take a look on refreshing the existing Provider Development Guide document? I don't think I have the bandwidth to do that much, but at least some minor fixes. We just started on our first provider, and as crossplane noobs, we found the PDG. And it is outdated, oh yes. 😅

@negz Which provider is considered the "golden" provider, doing just about everything according to best practices, these days? 😉 I would expect provider-template to come pretty close - but it shows limited stuff (for obvious reasons).

[chlunde]

For new resources:

• Working examples (that fit together with the other examples, for example named references)
• Tests/coverage, what kind of tests do we require? What's nice to have?
• Manual testing, test not only create and delete but also modifications

For reviews/changes:

• alpha vs. beta API changes
• release note procedure?
• alpha vs beta requirements

for reviewers:

• Review process - you review the code, tests and examples, obviously. But what more is expected for an alpha resource? Should the reviewer fully understand the service and look for non-obvious issues? Should you run the code end-to-end and verify the example? Test modifications? What more?

for maintainers:

• Who merges, when? Especially when multiple maintainers have discussed the issue at some point but not left a formal review. Probably not really an issue when the above questions are answered 😄

[negz]

I don't think I have the bandwidth to do that much, but at least some minor fixes.

Minor fixes are more than welcome!

Which provider is considered the "golden" provider, doing just about everything according to best practices, these days?

As you mention, provider-template is typically the best but it is a little basic. Apart from that it's really hard to say. The AWS provider is the most extensive and mature, but because much of it is generated code it's not the best reference for folks building their own providers by hand.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions]

Crossplane does not currently have enough maintainers to address every issue and pull request. This issue has been automatically marked as stale because it has had no activity in the last 90 days. It will be closed in 7 days if no further activity occurs. Leaving a comment starting with /fresh will mark this issue as not stale.

[github-actions]

Crossplane does not currently have enough maintainers to address every issue and pull request. This issue has been automatically marked as stale because it has had no activity in the last 90 days. It will be closed in 7 days if no further activity occurs. Leaving a comment starting with /fresh will mark this issue as not stale.

[jeanduplessis]

@plumbis does it make sense to transfer this issue to crossplane/docs or is it already actioned/covered by another open issue there?

[plumbis]

There was an explicit ask by c/c maintainers to keep development related content solely inside the c/c repository and not to put development/contributing docs in the docs repo.

[github-actions]

Crossplane does not currently have enough maintainers to address every issue and pull request. This issue has been automatically marked as stale because it has had no activity in the last 90 days. It will be closed in 14 days if no further activity occurs. Leaving a comment starting with /fresh will mark this issue as not stale.

[jbw976]

/fresh

[github-actions]

Crossplane does not currently have enough maintainers to address every issue and pull request. This issue has been automatically marked as stale because it has had no activity in the last 90 days. It will be closed in 14 days if no further activity occurs. Leaving a comment starting with /fresh will mark this issue as not stale.