Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: remove tutorial chapters that are covered by the how-to guide #1511

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

tonyandrewmeyer
Copy link
Contributor

The (k8s) tutorial is currently quite long, and we'd like it to be shorter so that it's easier for charmers to get going.

The plan is that the features described in the tutorial should be the chapters. Namely:

  • A simple web server with endpoints that can be used, including metrics
  • Integration with postgresql
  • An action to be able to manually interact with postgresql
  • COS integration, including logs and metrics

This PR removes the chapters:

  • Exposing the workload version (the existing how-to guide already covers this, and it's not essential for a charm)
  • Storing state (we would generally prefer that charms don't do this, so shouldn't encourage it, and it'll be covered by a how-to guide before this PR is ready for review)
  • Exposing a port via K8s (too small for a tutorial chapter, and the existing how-to guide already covers this - and was based mostly on this chapter, in the knowledge that it'd be replacing it)
  • Write Harness tests - the new unit testing (Scenario) chapter is merged into this. The testing chapters need to be migrated into sections at the end of each chapter, but that's work for another day and another person. This just stops teaching new charmers to write Harness tests

There are a few other small tidy-ups, particularly around whitespace and removing old commented text.

@tonyandrewmeyer
Copy link
Contributor Author

tonyandrewmeyer commented Dec 18, 2024

The k8s-tutorial-sdk repository will also need to be updated, including renaming a bunch of chapters, in sync with this getting merged.

I'd suggest that we don't merge this until the Discourse versions go away, if possible, so that the example repo can always match the live version.

```text
git clone https://github.com/canonical/juju-sdk-tutorial-k8s.git
cd juju-sdk-tutorial-k8s
git checkout 05_preserve_charm_data
git checkout -b 06_create_actions
git checkout 03_integrate_with_psql
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we get rid of the "nn_" prefixes on the branch names to avoid having to rename things (more than the once)?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wondered about that too. Adding (especially inserting) or removing a chapter is annoying, because there's this chunk at the start, plus a similar one at the end, as well as previous/next links - and this repo and the tutorial one need to be kept in sync. I think we can probably automate a bunch of that now that we don't have to work with Discourse.

On the other hand, it is nice to have a clear order, and that's missing from the docs now that they don't have leading numbers. We probably aren't adding/removing pages all that often.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants