No docs for 0.9 versions

[alexeagle]

https://github.com/bazelbuild/rules_pkg/blob/main/docs/latest.md documents 0.8.2

Is this a manual process on releases?

[aiuto]

It's manual. I have not found the time payoff in automating it robustly.

Doing 'latest' is easy, or not, depending on what we consider latest to mean. I've been treating it as head, but the issue description might imply you take it to mean latest release.

The versioned releases are their own question. I don't think having a distinct text for every release adds value. It encourages web search to find obsolete docs. OTOH, some people do want the docs for the specific thing they are using.

Anyway, #739 and #740 are out to do some updates.

[alexeagle]

I'd like to fix this permanently to reduce the maintenance burden in this repo. I have the time to automate it robustly.

https://github.com/bazel-contrib/rules-template/tree/main/docs is the pattern used in a dozen rulesets. It's just a regular test that asserts the markdown at HEAD always matches the stardoc output at HEAD. Every PR updates the docs. Users can use the GitHub UI to read docs at any tag they choose.

Can I send you a PR for this, rather than a special effort for 0.9? I think we should cut releases regularly, but the more effort required, the less likely we are to find the time to perform them.

[aiuto]

How does this account for the post processing pipeline that assembles the unified doc set and fixes the bad stardoc generation.

On Tue, Aug 22, 2023 at 10:38 AM Alex Eagle @.***> wrote:

I'd like to fix this permanently to reduce the maintenance burden in this repo. I have the time to automate it robustly.

https://github.com/bazel-contrib/rules-template/tree/main/docs is the pattern used in a dozen rulesets. It's just a regular test that asserts the markdown at HEAD always matches the stardoc output at HEAD. Every PR updates the docs. Users can use the GitHub UI to read docs at any tag they choose.

Can I send you a PR for this, rather than a special effort for 0.9? I think we should cut releases regularly, but the more effort required, the less likely we are to find the time to perform them.

— Reply to this email directly, view it on GitHub https://github.com/bazelbuild/rules_pkg/issues/716#issuecomment-1688317986, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAXHHHH4I3I2THEDM7BJL43XWS77ZANCNFSM6AAAAAA2JSIFDI . You are receiving this because you commented.Message ID: @.***>

[alexeagle]

There's no post-processing. We can make a unified experience with a table of contents like https://github.com/aspect-build/bazel-lib#public-api and for bad stardoc generation, I either fix that upstream or use a fork of stardoc with some of my fixes.

Would you like a PR to see what this will look like?

[aiuto]

I'm not going to fork stardoc. I will keep nudging them to fix it instead. How about if the update rule from the template were modified to take two parameters

• the target which generates the doc file(s)
• the page(s) to place them at.

That would incorporate any doc generation scheme, stardoc or not.

On Tue, Aug 22, 2023 at 1:24 PM Alex Eagle @.***> wrote:

There's no post-processing. We can make a unified experience with a table of contents like https://github.com/aspect-build/bazel-lib#public-api and for bad stardoc generation, I either fix that upstream or use a fork of stardoc with some of my fixes.

Would you like a PR to see what this will look like?

— Reply to this email directly, view it on GitHub https://github.com/bazelbuild/rules_pkg/issues/716#issuecomment-1688618850, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAXHHHEUUIA62YJUUKCBMWTXWTTLHANCNFSM6AAAAAA2JSIFDI . You are receiving this because you commented.Message ID: @.***>

[alexeagle]

Can you point to the stardoc bug? I wonder if it's the dedenting issue that caused me to fork but was recently fixed.

[aiuto]

https://github.com/bazelbuild/stardoc/issues/120 https://github.com/bazelbuild/stardoc/issues/118 https://github.com/bazelbuild/stardoc/issues/98

There are probably others. I'm not sure if the stardoc rule lets me control the order of methods declared, or if it would sort them alphabetically (that would be a new bug).

The non-generated text that I need could be put in the silverlight template.

[alexeagle]

Thanks, I replied to all three of those issues with the techniques we use for Aspect's rulesets. IMHO we do a really nice job providing high-quality, readable API docs for users, without having to invent any mechanisms that live in the ruleset repo to workaround stardoc issues. If you have any time, I'd love to spend 15min walking through that with you.

[alexeagle]

There are docs for 0.9 now, so this is solved as reported. I get the sense that you're not really interested in automating the docs process and don't want to make a big deal out of it.

[aiuto]

There is some push from internal security teams to redo the release process in specific ways. I'm in negotiation with them about their requests

On Sun, Oct 1, 2023, 5:37 PM Alex Eagle @.***> wrote:

Closed #716 https://github.com/bazelbuild/rules_pkg/issues/716 as completed.

— Reply to this email directly, view it on GitHub https://github.com/bazelbuild/rules_pkg/issues/716#event-10519898600, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAXHHHGVUCQJDW2S5UZQDEDX5GEZZANCNFSM6AAAAAA2JSIFDI . You are receiving this because you commented.Message ID: @.***>

[alexeagle]

Could I get a contact info from someone there? I'd like to get the Bazel-contrib rules-template that all the community rules are based on

[aiuto]

+Tobias Werth @.***> The best contact for Bazel policy is Tobi, or myself if strictly about rules_license or rules_pkg.

On Mon, Oct 2, 2023 at 3:33 AM Alex Eagle @.***> wrote:

Could I get a contact info from someone there? I'd like to get the Bazel-contrib rules-template that all the community rules are based on

— Reply to this email directly, view it on GitHub https://github.com/bazelbuild/rules_pkg/issues/716#issuecomment-1742290324, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAXHHHHQWOB3ZTLTWLON5Y3X5IKYNANCNFSM6AAAAAA2JSIFDI . You are receiving this because you commented.Message ID: @.***>

[meisterT]

cc @comius @meteorcloudy

[alexeagle]

Probably better to take this to a dedicated issue: https://github.com/bazel-contrib/rules-template/issues/99