Where and how to use {{securecontext_inline}}

[skyclouds2001]

Currently, there are two ways to indicate that a page is only available in Secure Context ———— {{securecontext_inline}} and {{securecontext_header}}. They are used for same purpose but for different situations in documentation.

But the fact is, the usage between {{securecontext_header}} and {{securecontext_inline}} is every different: {{securecontext_header}} widely used but {{securecontext_inline}} is rawly used. Also, {{securecontext_header}} is mentioned in Writing guide pages but {{securecontext_inline}} not. Besides, {{securecontext_inline}} its size is quite big and a little not pretty, compared with other inline-type macros ———— {{non-standard_inline}} {{deprecated_inline}} {{experimental_inline}} {{readonlyinline}} {{optional_inline}}. This makes it is more likely to break the line then other inline-type macros. And using this maight be confused with {{securecontext_header}} which could express the same meaning. So, personnally now I'd prefer not to use {{securecontext_inline}} in documentation writing.

I wonder if it is better to also use {{securecontext_inline}} to indicate secure context with {{securecontext_header}}, and it is necessary to express the secure context requirement to readers in situations that might be fit to use {{securecontext_inline}} (like API's interfaces in API summary, interface's property in interface summary).

some examples that use {{securecontext_inline}}

• https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API
• https://developer.mozilla.org/en-US/docs/Web/API/Geolocation
• https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates
• https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition
• https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError

[hamishwillee]

I don't think of we need {{securecontext_inline}}. My reasoning is that unlike deprecated/experimental/non-standard you're not highlighting a decision as to whether something should be used, but how it is used. You're still going to have to use it if you need the feature, and you can find that about the secure context from the top level API or the interface level. You shouldn't usually need to know about individual interfaces needing the context from that top level.

But if we do decide it is useful there should be a guide on this, and it should be applied consistently everywhere.

[teoli2003]

I don't know if there are such cases, but I would say the only cases where it would be useful is if an interface is NOT restricted to secure contexts, but one of its members (a method or a property) is.

But I don't have such an example (except on Window but these really are global, and we may want to exclude them).

Note: even in such cases, using the header macro on the member page may be enough.

[teoli2003]

Yes, I think the only point of disagreement is:

In an interface page

Alternative 1:

• if the whole interface is secure context
  • tag the page with a header macro
    • don't tag the individual members with badge

vs

Alternative 2:

• if the whole interface is secure context
• tag the page with a header macro
  • also tag the individual members with badge

I have no strong feelings here.

Alternative 1:
Pro: no Christmas tree
Con: when you are on a long page, you don't know which kind of interface page you are.

Alternative 2:
Pro:

• consistency between all interface pages (without looking at the top of the page)
• consistency with other badges on every interface page

Con: verbose (a bit of a Christmas tree)

I would prefer alternative 1, but I am neutral about alternative 2 (I will not oppose it).

[skyclouds2001]

I also prefer with Alternative 1

• if the whole interface is secure context

  • tag the page with a header macro

    • don't tag the individual members with badge

because if an interface requires secure context, then its methods or properties definitely requires secure context, but if an interface does not require secure context, then its methods or properties may still require secure context

[skyclouds2001]

using a badge (I think there is consensus on this)

We have consensus that we want to use a badge with consistent appearance.

tagging interfaces with the header macro if everything is secure context (I think there is consensus on this)
individually tagging members if they are secure context only.

I'm not certain this is unambiguous. I think you are saying:

• In interface page

  • if whole interface is secure context

    • tag the page with header macro
    • don't tag the individual members with badge

  • if only part of the interface is secure context

    • don't tag the page with header macro
    • tag the individual members with badge

• In property/method page

  • tag the page with header macro if it is secure context and not otherwise. Irrespective of the interface.

If not, can you expand?

Another possible situation is for api landing page (also constructor/event pages, but they could combine with property/method pages)

[hamishwillee]

I prefer Alternative 1 too. Sounds like broad consensus there.

What about property/method pages? They always get the secure context header (if require secure context)?

[teoli2003]

Yes, they should: there is no guarantee that a reader will read the interface page first.

[wbamberg]

It looks to me like you've mixed up the proposals and the pros/cons?

Alternative 1:
...
* don't tag the individual members with badge
...
Alternative 1:
...

Con: verbose (a bit of a Christmas tree)

[skyclouds2001]

yes, my mistake

[teoli2003]

I mixed and corrected.

[hamishwillee]

Consensus?

1. Fix up the secure-inline macro to be a badge.

2. In an interface page (Alternative 1)

   • if the whole interface is secure context
     • tag the page with a header macro
     • don't tag the individual members with badge
   • if only part of the interface is secure context
     • don't tag the page with header macro
     • tag the individual members with badge

3. Tag property/method pages with secure context, irrespective of the interface.

4. The API overview should have a header too if the whole thing is secure context. Not sure about what it should do if "partially secure context". I guess same rule as for interfaces.

[Rumyra]

I'm ok with this proposal 👍

(Apologies I didn't bring it up yesterday @teoli2003 )

[hamishwillee]

So, who can fix the badge? Do we have enough "approval" to update our docs with this as a guideline? I'd say yes.

[teoli2003]

Yes, it looks like we have only approvals and nobody against it, which is the definition of a consensus, so we can move forward.

[teoli2003]

I created the yari PR to fix the look of the badge: mdn/yari#10214

[skyclouds2001]

Current usage of this macros:

except those will remove via #31302

• BaseAudioContext.audioWorklet

• Crypto.subtle

• CSS.paintWorklet

• Screen.isExtended Screen/change_event

• Window.getScreenDetails()

• Clipboard API

• Sensor APIs

• Window Management API

[OnkarRuikar]

So, who can fix the badge? Do we have enough "approval" to update our docs with this as a guideline? I'd say yes.

There is a "Mozilla-wide Production Change Freeze" till Jan 2 so till then the inline badge can't be fixed.
Any idea how the docs can be updated? May be we can write a script to fetch the statues from webref repo. Or do it manually if there are only few features that require securecontext.

[hamishwillee]

I think the first step would be to update the macro and template docs with "the rule" so that we all know what we're doing going forward.

W.r.t. "how", I think a script would make sense. I bet @teoli2003 has some ideas about how to get started :-)

[teoli2003]

I agree we should update the macro and the meta docs first.

If the macro change is only merged on Jan 2, that's not a problem: we use the inline macro only in specific cases that often already use the ugly look of the macro.

Then we need to update, ideally with a script that can run weekly afterward.

[OnkarRuikar]

Does the decision apply to all the inline macros, e.g. status macros {{Experimental_inline}}?

[OnkarRuikar]

It was decided to have a separate discussion for inline status macros.