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

Add upgrading to 4.x docs #6930

Merged
merged 12 commits into from
Dec 13, 2024
Merged

Add upgrading to 4.x docs #6930

merged 12 commits into from
Dec 13, 2024

Conversation

j1m-ryan
Copy link
Member

@j1m-ryan j1m-ryan commented Dec 6, 2024

Proposed changes

Adds upgrading to 4.x docs page
Fix some small aspects of the create license secret page (linking to nim, some header changes)

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

@j1m-ryan j1m-ryan added the documentation Pull requests/issues for documentation label Dec 6, 2024
@j1m-ryan j1m-ryan requested review from a team as code owners December 6, 2024 15:33
Copy link

github-actions bot commented Dec 6, 2024

Deploy Preview will be available once build job completes!

Name Link
😎 Deploy Preview https://frontdoor-test-docs.nginx.com/previews/nginx-ingress-controller/6930/

Copy link

codecov bot commented Dec 6, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 52.64%. Comparing base (df9b043) to head (e90efce).
Report is 6 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #6930      +/-   ##
==========================================
- Coverage   52.95%   52.64%   -0.31%     
==========================================
  Files          88       88              
  Lines       20623    20758     +135     
==========================================
+ Hits        10921    10929       +8     
- Misses       9255     9372     +117     
- Partials      447      457      +10     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Copy link
Contributor

@ADubhlaoich ADubhlaoich left a comment

Choose a reason for hiding this comment

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

LGTM generally.

I'd consider moving this document into the installation folder, and linking to it from the release page where relevant.

There's text in the structured logging section that's repeated that could be put outside of the tabs: right now that structure feels a bit weird because of how everything is laid out.

A numbered list suggests a sequence of steps: point 3 is a piece of information, not an instruction, and point 4 is an optional step depending on the environment. If it's not a critical step necessary for all users, we prefer to give optional steps their own section.

Although it might feel slightly excessive due to the length of the document, converting some of the steps into subsections would demarcate the steps easily and make formatting easier: there's a pattern in our documentation I dislike where everything is a list item.

List items are all indented and the gymnastics around making sure it formats and displays properly mean you're incentivized to write as little as possible.

j1m-ryan and others added 3 commits December 10, 2024 14:55
Co-authored-by: Alan Dooley <a.dooley@f5.com>
Signed-off-by: Jim Ryan <j.ryan@f5.com>
@j1m-ryan j1m-ryan requested a review from ADubhlaoich December 10, 2024 14:59
j1m-ryan and others added 2 commits December 10, 2024 16:22
Co-authored-by: Venktesh Shivam Patel <ve.patel@f5.com>
Signed-off-by: Jim Ryan <j.ryan@f5.com>
Copy link
Contributor

@ADubhlaoich ADubhlaoich left a comment

Choose a reason for hiding this comment

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

Blocking this temporarily: I'm going to push some changes directly to the branch, discussed with @j1m-ryan .

vepatel and others added 3 commits December 12, 2024 15:10
This commit updates the information architecture and metadata
for documentation related to NGINX Ingress Controller 4.0.0.

It clarifies the relationship between certain documents, moves or hides
pages and delineates sections of the upgrade documentation while
making the text instruction more concise and precise.
Copy link
Contributor

@ADubhlaoich ADubhlaoich left a comment

Choose a reason for hiding this comment

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

Adding an approval following my direct edits.

The commit message provides the context of the changes:

This commit updates the information architecture and metadata
for documentation related to NGINX Ingress Controller 4.0.0.

It clarifies the relationship between certain documents, moves or hides
pages and delineates sections of the upgrade documentation while
making the text instruction more concise and precise.

There are some contextual changes that might warrant extra explanation: using discrete sections instead of itemizing the instructions in a single list improves the readability and sequence of steps involved.

The license secret documention was moved to its position to reflect that the instructions are contextless, and might be involved with a different use case/path than just upgrading or installing NGINX Ingress Controller (such as building it yourself).

@j1m-ryan j1m-ryan added the needs cherry pick Cherry pick this PR into a release branch label Dec 13, 2024
@j1m-ryan j1m-ryan requested review from jjngx and vepatel December 13, 2024 10:28
@j1m-ryan j1m-ryan merged commit 1e5ee04 into main Dec 13, 2024
30 checks passed
@j1m-ryan j1m-ryan deleted the chore/r33-upgrade-doc branch December 13, 2024 11:00
nginx-bot pushed a commit that referenced this pull request Dec 13, 2024
* add upgrading to 4.x page

* Update upgrading docs

* Delete upgrading-to-4.x.x.md

* Apply suggestions from code review

Co-authored-by: Alan Dooley <a.dooley@f5.com>
Signed-off-by: Jim Ryan <j.ryan@f5.com>

* Apply suggestions from code review

Co-authored-by: Venktesh Shivam Patel <ve.patel@f5.com>
Signed-off-by: Jim Ryan <j.ryan@f5.com>

* feat: Update IA, metadata and content related to v4 upgrades

This commit updates the information architecture and metadata
for documentation related to NGINX Ingress Controller 4.0.0.

It clarifies the relationship between certain documents, moves or hides
pages and delineates sections of the upgrade documentation while
making the text instruction more concise and precise.

---------

Signed-off-by: Jim Ryan <j.ryan@f5.com>
Co-authored-by: Jakub Jarosz <99677300+jjngx@users.noreply.github.com>
Co-authored-by: Alan Dooley <a.dooley@f5.com>
Co-authored-by: Venktesh Shivam Patel <ve.patel@f5.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Pull requests/issues for documentation needs cherry pick Cherry pick this PR into a release branch
Projects
Status: Done 🚀
Development

Successfully merging this pull request may close these issues.

5 participants