Add a guide for upgrading to a new starter pack.

[odadacharles]

• Have you updated CHANGELOG.md with relevant non-documentation file changes?
• Have you updated the documentation for this change?

---

This pull request address the lack of an upgrade guide for users upgrading from one extension based starter pack to another.
Also addressed this issue: #524
Preview: https://canonical-starter-pack--529.com.readthedocs.build/529/how-to/update-starter-packs/extendable/

[YanisaHS]

LMK if you have any questions / comments on what I've left! I went through it pretty quickly, wouldn't be surprised if something was unclear :)

[YanisaHS]

I don't think you need to provide as beginner-level guidance like details on how to approach a error message, internet connection, etc.

Also, isn't make clean-doc the one they should use? (I might be misremembering though, I didn't check)

[akcano]

clean-doc drops the venv as well, so it's cleaner

[odadacharles]

I find that make clean-doc is not as thorough as make clean and leaves some files behind. If I'm reading the Makefile correctly, it also seems like running make clean also runs make clean-doc

[YanisaHS]

Can we give more specific common causes of errors?

[odadacharles]

I'll see what can be added to the list

[tang-mm]

Nice write-up! I left a few suggestions to clarify the context

[tang-mm]

It will be helpful to distinguish the files that are definitely not needed from those that might be in use.

-   `.github/pull_request_template.md` 
-   `.github/CODEOWNERS`
-  `.github/workflows/test-starter-pack.yml`
-   `.github/workflows/sphinx-python-dependency-build-checks.yml`

Please make sure to include the directory path as well

[odadacharles]

Sure thing. I'll make those changes

[odadacharles]

I'm actually not sure which files are definitely not needed. I'll need more information from someone else. But I included the directory paths.

[a-velasco]

I generally agree with @tang-mm, but I am not sure exactly what I'd say here either. Some of the files are general repo artifacts, like pull_request_template.md and CODEOWNERS, so anything like this coming from a starter pack update has a chance of interfering with existing files.

But others are starter pack-specific:

• sphinx-python-dependency-build-checks.yml is only needed by a small handful of specific repos, so I'd say that if the user didn't have this before, remove it
• If reuse/links.txt and substitutions.* were previously customized in your project, they cannot be deleted

So maybe for now we can just be clear about what files have the potential to break your build. Perhaps something like:

These files can be deleted safely:
 
-   `pull_request_template.md`
-   `sphinx-python-dependency-build-checks.yml`
-   `CODEOWNERS`

These files can be deleted as long as they are not being used in your docs:

-   `reuse/links.txt`
-   `mermaid.txt`
-   `substitutions.txt`
-   `substitutions.yaml`

In the future, we can edit this to link to a page that explains the function of those files more precisely. I think this is enough for now.

[a-velasco]

Great comments from @YanisaHS and @tang-mm - I'll wait for those to get resolved before doing another pass.

What stands out to me right now is that we've now got two guides:

• Migrate from the pre-extension starter pack
• Upgrade to newer version of starter pack

and the second title also describes the goal of the first guide.

I'd like to propose simplifying the navigation by creating a high-level parent section:

• Upgrade the starter pack
  • Migrate from the pre-extension starter pack
  • Upgrade the new starter pack

This parent section could have some brief guidance on how to tell what version of the starter pack you're using (see @tang-mm 's comment) - and therefore which guide you need.

Unblocking my review status so this PR doesn't stall while I’m OOO. I’ll defer to the other reviewers for the final sign-off

[a-velasco]

Thank you for all your hard work on this guide, @odadacharles!

[yhontyk]

I am trying to follow the procedure right now and it is not clear which of these I should pick:

Migrate from the pre-extension starter pack
Upgrade the new starter pack

Intuitively, I understand that the former is something that is "old" and the latter is something that is "new" but it's not clear from the title.
My lazy brain also read "pre-extension" as "pre-existing" which added to the confusion. 😓

We version SP but how can I actually check which version I am using? If we could run the command or see somewhere in the config file the version number, it would be way easier to make a clear title.

[medubelko]

@odadacharles Thanks for this! :)

This has already been under a lot of scrutiny, so I've focused on big-picture questions. These are suggestions for the architecture of these docs, and a few reST concerns.

I think to be clear to our users, we should try for a structure like this:

Path	TOC entry	Page title
how-to/update/extendable.rst	How-to > Update > Extendable	Update extendable documentation
how-to/update/pre-extension.rst	How-to > Update > Pre-extension	Update pre-extension documentation

This would require changing Update the documentation, because it occupies the update folder. But that should be a simple fix.

@jahn-junior How do you feel about "extendable" or "modular" for what came after the extension change? A less ambiguous way would be to pin it by version number (pre- and post-1.3.0).

[odadacharles]

Hi @medubelko , I've addressed most of your comments/suggestions, except the one on the update directory. Since that's already taken up by the documentation, we'll need to discuss how best to address that, plus whether the ones on documentation should all be in an actual directory. CC: @a-velasco
Let me know what you think.

[a-velasco]

Some great points were brought up during this review, and I definitely expect that this page will see future edits and revisions.

But in the spirit of moving things along, I'd consider the remaining comments non-blocking, and I believe this guide in a good state to merge and make it available to people.

[a-velasco]

I generally agree with @tang-mm, but I am not sure exactly what I'd say here either. Some of the files are general repo artifacts, like pull_request_template.md and CODEOWNERS, so anything like this coming from a starter pack update has a chance of interfering with existing files.

But others are starter pack-specific:

• sphinx-python-dependency-build-checks.yml is only needed by a small handful of specific repos, so I'd say that if the user didn't have this before, remove it
• If reuse/links.txt and substitutions.* were previously customized in your project, they cannot be deleted

So maybe for now we can just be clear about what files have the potential to break your build. Perhaps something like:

These files can be deleted safely:
 
-   `pull_request_template.md`
-   `sphinx-python-dependency-build-checks.yml`
-   `CODEOWNERS`

These files can be deleted as long as they are not being used in your docs:

-   `reuse/links.txt`
-   `mermaid.txt`
-   `substitutions.txt`
-   `substitutions.yaml`

In the future, we can edit this to link to a page that explains the function of those files more precisely. I think this is enough for now.

[medubelko]

Some necessary technical fixes. I'll commit these directly to save time.

[medubelko]

LGTM, thanks @odadacharles!

[jahn-junior]

@medubelko @odadacharles Sorry I'm late to the party. I'll hold off on a formal review, as it seems this has gotten plenty of love already. I'll just leave a few thoughts on this question in case we revisit it later:

@jahn-junior How do you feel about "extendable" or "modular" for what came after the extension change? A less ambiguous way would be to pin it by version number (pre- and post-1.3.0).

• extendable: I believe the more common word in this context is "extensible". "Extendable" typically refers to a physical characteristic. Either way, I'm not a huge fan of this, as the Starter Pack wasn't any less extensible before we introduced canonical-sphinx.
• modular: This is more accurate, but I don't think users will have a sense of how modular their version is or isn't. If I weren't a contributor, seeing this in a title wouldn't help me make my decision.
• post-1.3.0: This is my preferred option, as it gives users something they can compare against directly to see where they stand. It's not the prettiest in writing, but I think it's a worthwhile sacrifice for clarity.

Once most of Canonical is on a semi-recent version, this will get less important. At that point, I think we'll be able to refer to these as the "the pre-extension Starter Pack" and "the Starter Pack".