This commit makes a number of changes to clarify what the precise steps
are to install, upgrade and uninstall NGINX Ingress Controller
- The Install document clarifies necessary steps
- Uninstall steps have been moved to the bottom of the document
- Upgrade instructions have been moved into their own document
The changes made focused on clarifying the critical path for one single
user story, as lots of unnecessary contextual information was being
provided, which was causing confusion.
With this commit, the general reading and execution flow for these
deployment steps become more coherent. Similar changes may be made for
Manifests documentation, if common steps are identified.
As part of the work, a number of include files have been updated or created
that are shared with NGINX Plus, to ensure the documentation around
obtaining an NGINX Ingress Controller image with Docker are consistent.
Subsequently, process documentation for managing includes was split from
the style guide and made into its own file due to the anticipated length
as reference information.
---------
Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com>
This commit updates the Hugo guidance to accurately reflect the usage of
our most common shortcodes, and guides people away from the ones that
have been removed or will be removed soon based on Mainframe changes.
The guidance is not fully inclusive: we have not yet determined where
full documentation for all theme elements should live (Such as a
publicly-facing design system), but it should cover the most commonly
used shortcodes.
The pull request template has also been updated in the same manner,
attempting to focus on critical information for contributors. The
checklist was previously quite long: it has been reduced to essential
elements, and reframed as a direct, personal commitment.
The detail underneath the "Proposed changes" has been shifted to inline,
hidden guidance, following a similar pattern in our Hugo archetypes.
Some information from the old checklist has been moved there, but it
otherwise covers the same ground as the old guidance.
It refers to and reinforces our standards asserted by our Git
conventions documentation, and will not create visual noise within the
PR should the contributor choose not to remove it.
* Update closed-contributions.md based on user testing
* Update documentation/closed-contributions.md
Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com>
---------
Co-authored-by: Alan Dooley <a.dooley@f5.com>
This commit removes the CHANGELOG file from the repository, as it was
not being used. The README and CONTRIBUTING files have been streamlined,
and now more accurately reflect the user flow when contributing.
Some GitHub templates have been updated to reflect these changes, and
also include relative links instead of axiomatic blobs, which will make
finding and updating links easier in the future.
This commit moves our git conventions to their own
discrete page, and adds information that was previously
not written down anywhere, such as our general
branch management strategy.
Beyond documenting these conventions, an initial pre-commit
configuration has been added, which can be used as a guardrail
to enforce some of the conventions, such as requirements
around commit message length. A hook provided by the
pre-commit maintainers is also configured to prevent
commits directly to the main branch.
These configurations may be adjusted in the future based
on feedback, and there is additional follow-up work to
add a template for the git commit message. I had a working
implementation but decided to scrap it in favour of
minimising the number of dependencies.
This commit adds guidance on article usage when referring to
product names, which was notably absent. The section as a whole
will likely be rewritten in the future for conciseness.
---------
Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com>
Co-authored-by: Alan Dooley <a.dooley@f5.com>
* chore: update Makefile to handle hugo bump to latest
* chore: update hugo version ref in CONTRIBUTING_DOCS
* CI: Update build-push job SHA ref
---------
Co-authored-by: Alan Dooley <a.dooley@f5.com>
This commit adds an IA heuristics page to our process documentation. The
NGINX DocOps teams spends a lot of time engaged with IA and is
increasingly involved with using heuristics to assess content.
This commit moves and updates some of the process documentation for the
repository. This is an iterative process, which will continue to improve
as time goes on. Some of the changes include:
- Moving the closed contributions document into the documentation folder
- Moving and reframing the F5/NGINX document as "Maintainers etiquette"
- Moving and renaming the "Managing content with Hugo" document
- Moving the style guide from the templates folder
These files will likely be updated in a subsequent PR as we clarify the
contribution process and user flow of other process artefacts, such as
the pull request and issue templates.
Although we do not draw attention to it, the templates folder is being
retained for reference until the style guide and Hugo archetypes contain
the relevant, useful information.
This commit adds a new documentation folder to the repository, with a
discrete section for proposals. I will be using this folder in the
future to organise more process documentation.
NGINX App Protect WAF has had a lot of fundamental design problems with
how its documentation is structured due to historic changes in the
direction of the product. Since those changes, the documentation has not
changed to account for it.
