Add a guide about upgrading applications without downtime

[pleshakov]

Proposed changes

Problem:
As a user of NKG, I want a guide to explain the different strategies I can upgrade my application (NOT NKG) while using NKG specific features (such as traffic splitting) So that I minimize the downtime my application encounters.

Solution:

• Add a guide that covers NKG specific features that help upgrade applications without downtime
• Introduce a new /docs/guide folder for guides.
• Add a link to the guides folder from the main README.

Testing: none

Closes #704

Checklist

Before creating a PR, run through this checklist and mark each as complete.

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have checked that all unit tests pass after adding my changes
• I have updated necessary documentation
• I have rebased my branch onto main
• I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

[sjberman]

I'd also tag someone from the docs team and PM to do a review of this.

[kate-osborn]

Great doc! Just a couple small comments

[kate-osborn]

🚀

[ADubhlaoich]

I have pushed a large amount of changes to the document which restructure the text and rephrase much of the content. Most of the changes were for the sake of imperative instructions and removing various qualifiers, making the text more concise.

Some of these changes, however, do not pass due to the Markdown line length checker. What convention is that specific length based on?

There are many instances of links written in a footnote notation style which is unprecedented elsewhere in NGINX; most of them could be written with regular inline markdown links.

I can push additional changes to fix the Markdown checks but they would be prioritising passing the check as opposed to the readability. You might find it useful to check out the "Content Types and Templates" internal page for an example of the information architecture used elsewhere for future docs.

[pleshakov]

@ADubhlaoich

I have pushed a large amount of changes to the document which restructure the text and rephrase much of the content. Most of the changes were for the sake of imperative instructions and removing various qualifiers, making the text more concise.

👍

Some of these changes, however, do not pass due to the Markdown line length checker. What convention is that specific length based on?

the length limit is 80. We choose it for all markdown files in our repo, so that is is easier read the source file and to review.

I made a few changes based on your changes. Mainly:

• removed "It ensures that clients attempting to access your application will receive standard response codes (such as 502) instead of empty responses during upgrades." because this is not the goal of the guide -- the goal is to prevent downtime, which are 502 responses.
• renamed "Endpoint switching" to "Upstream Servers Updates" - to make it use NGINX terminology.
• a few smaller changes and fixes

Please let me know if those are ok.

[ADubhlaoich]

Approved with one minor suggestion - "Upstream Servers Updates" => "Upstream Server Updates". Updates is already pluralised and making Server singular is better for readability, with the possibility of multiple implied in context.

If the plan at a later stage is to serve the docs through a website, the markdown line length checking may become an issue since the line length is currently prioritising GitHub readability.

IDEs and web frameworks have no issue with word wrapping paragraphs of arbitrary line length, so this may become the writing equivalent of technical debt that'll need to be addressed if the default expectation of reader consumption through GitHub changes.