Guidelines for documenting usntable contributions (#49296)

[Tokazama]

This adds review of "Writing Documentation" to contributors checklist and requires that unstable parts of an API be clearly annotated as subject to change without notice. This should allow us to more consistently require documentation of internals without the risk of committing to a particular implementation for packages.

[KristofferC]

I think this is way too strong. And now Base is inconsistent with the style guide. This should have updated the docstrings as well so one can see what the effect is?

[Tokazama]

I think this is way too strong. And now Base is inconsistent with the style guide. This should have updated the docstrings as well so one can see what the effect is?

How can we update the docstrings to follow this if there's no record of what is an unstable API?

[KristofferC]

if there's no record of what is an unstable API?

The functions not in the manual are internal.

[ViralBShah]

We can naturally not document every internal API. But also isn't it a good idea to document some that may have broad interest for compiler development as part of Dev docs?

[Tokazama]

I wasn't aware that everything that wasn't explicitly included in "julia/docs" was considered unstable. I'm not completely against adding this in to existing documentation but wouldn't we need to audit each case and ensure that isn't already in use somewhere since this instability isn't documented elsewhere?

[timholy]

If it wasn't in julia/docs, it's unstable regardless of whether people are actually using it (it's their fault for using it, not ours).

[ViralBShah]

Should we revert this PR?

[timholy]

I'd say so, unless an improved version is forthcoming.

[Tokazama]

Does the original proposal need to be changed or do we just need to add this notation to the docs that aren't in "julia/docs" docs need to be added?

[timholy]

I think both: if we haven't documented how we decide "internal," we should; but as @KristofferC points out, we don't currently live up to the standard espoused here, and it seems like a lot of work to maintain. So I would also lean towards reverting this.

[Tokazama]

This was definitely just a first stab at getting this out there so suggestions are welcome. We definitely aren't following this currently and it creates a lot more work. The @pure macro comes to mind when it was internal but required a bunch of work to not break other packages. So the idea is a little more work up front so we don't have to worry about problems changing stuff later

[ViralBShah]

I've reverted for now. Apologies for the noise. @Tokazama We can continue the discussion here.