docs(notifications): Adds notification documentation

[thomastaylor312]

This adds full documentation for the new pro feature of Notifications. It includes both instructions for the imperative steps (send-message step) as well as the new EventRouter type for event-driven notifications

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	ffb413f
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/69025b754b9f6400084213d8
😎 Deploy Preview	https://deploy-preview-5265.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 55.98%. Comparing base (60fba34) to head (ffb413f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5265   +/-   ##
=======================================
  Coverage   55.98%   55.98%           
=======================================
  Files         405      405           
  Lines       29858    29858           
=======================================
  Hits        16715    16715           
  Misses      12177    12177           
  Partials      966      966           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[krancour]

Wouldn't it be ignored for MessageChannel as well, which is only allowed to reference Secrets in the Project's namespace?

[krancour]

Now that I've looked at that section as well, I do see it's called out as ignored there also. Now I'm wondering if that field should just go away since it's used in neither case. wdyt?

[thomastaylor312]

I can remove references to it for sure. We are reusing the ObjectRef field in the actual CRD definition so the namespace is there no matter what

[krancour]

Definitely not something I feel we need to fix right this moment.

Devil's advocate... is there any reason it really needs to be an ObjectRef? If it were some other type that had only a name field, it's non-breaking to turn it back into an ObjectRef at some point in the future, should we need to.

I'm asking only because I always find it awkward when fields exist that one mustn't use, or can use but it will be ignored 100% of the time.

Again... not anything we need to put closure on here and now.

[thomastaylor312]

I don't think ObjectRef is in any way necessary. I picked it originally because it is the "canonical" way of referencing another object. Theoretically we could use the UID as well in the future. That isn't a good enough reason to keep it by any stretch of the imagination and I wouldn't mind trimming it to just a name

[krancour]

We have an established way now of labeling entire pages as being EE features, but I'm not sure we have an established way yet of marking a section of a more general page with some indicator that it's EE only. I guess it's time to figure out an approach.

[krancour]

Ugh... nevermind... sort of. I should have looked two lines down. Buuut... on pages where the entire page is exclusively EE content, these appear above the section heading. So there's a question about placement here maybe. No strong opinion here... just questions.

[thomastaylor312]

I personally think it makes more sense under a heading when in a page with "mixed" content. But I don't have a strong opinion here

[krancour]

We're establishing the precedent here. If it's that it goes above the heading if it's the whole page and under the heading if it's a section of that page, I'm fine with that.

[thomastaylor312]

Just as a heads up, when we put the span tag above the first H1, it messes up the automatic title in the sidebar. We can overwrite with sidebar_label, but this might be a reason we want to put everything below a heading (under the top H1 for a page where all the content is EE and under the specific section header for "mixed" content)