Skip to content

Improve documentation of SetupHooks, unexposing some internal constructors#11771

Merged
mergify[bot] merged 1 commit into
masterfrom
doc-hooks
May 17, 2026
Merged

Improve documentation of SetupHooks, unexposing some internal constructors#11771
mergify[bot] merged 1 commit into
masterfrom
doc-hooks

Conversation

@sheaf
Copy link
Copy Markdown
Collaborator

@sheaf sheaf commented Apr 29, 2026

Changes:

  • Add an usage overview that explains what the various hooks may be useful for.
  • Add a worked example for dynamicRule as it is the most complex aspect of the API.
  • Unexpose the gnarly RuleCommands constructors, advising usage of staticRule and dynamicRule instead.
  • Various small tweaks, including additional haddock comments for dynamicRule.

Template Α: This PR modifies behaviour or interface

@sheaf
Copy link
Copy Markdown
Collaborator Author

sheaf commented Apr 30, 2026

I've added a new "how to use SetupHooks" guide entry now.

Copy link
Copy Markdown
Member

@Mikolaj Mikolaj left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I totally approve!

Comment thread changelog.d/UnexposeRuleCommands.md
Comment thread Cabal-hooks/src/Distribution/Simple/SetupHooks.hs Outdated
Comment thread Cabal-hooks/src/Distribution/Simple/SetupHooks.hs Outdated
@sheaf sheaf changed the title Improve documentation of SetupHooks Improve documentation of SetupHooks, unexposing some internal constructors May 6, 2026
@sheaf sheaf added merge me Tell Mergify Bot to merge and removed attention: needs-review labels May 6, 2026
@mergify mergify Bot added ready and waiting Mergify is waiting out the cooldown period merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days queued labels May 6, 2026
@mergify
Copy link
Copy Markdown
Contributor

mergify Bot commented May 8, 2026

Merge Queue Status

This pull request spent 1 hour 39 minutes 16 seconds in the queue, including 1 hour 28 minutes 46 seconds running CI.

Waiting for any of
  • check-neutral = Validate post job
  • check-skipped = Validate post job
  • check-success = Validate post job
All conditions
  • any of [🛡 GitHub branch protection]:
    • check-neutral = Validate post job
    • check-skipped = Validate post job
    • check-success = Validate post job
  • #approved-reviews-by >= 2 [🛡 GitHub branch protection]
  • #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • #review-threads-unresolved = 0 [🛡 GitHub branch protection]
  • any of [🛡 GitHub branch protection]:
    • check-success = Doctest Cabal
    • check-neutral = Doctest Cabal
    • check-skipped = Doctest Cabal
  • any of [🛡 GitHub branch protection]:
    • check-success = Meta checks
    • check-neutral = Meta checks
    • check-skipped = Meta checks
  • any of [🛡 GitHub branch protection]:
    • check-success = docs/readthedocs.org:cabal
    • check-neutral = docs/readthedocs.org:cabal
    • check-skipped = docs/readthedocs.org:cabal
  • any of [🛡 GitHub branch protection]:
    • check-success = fourmolu
    • check-neutral = fourmolu
    • check-skipped = fourmolu
  • any of [🛡 GitHub branch protection]:
    • check-success = hlint
    • check-neutral = hlint
    • check-skipped = hlint
  • any of [🛡 GitHub branch protection]:
    • check-success = Bootstrap post job
    • check-neutral = Bootstrap post job
    • check-skipped = Bootstrap post job
  • any of [🛡 GitHub branch protection]:
    • check-success = whitespace
    • check-neutral = whitespace
    • check-skipped = whitespace
  • any of [🛡 GitHub branch protection]:
    • check-success = Check sdist post job
    • check-neutral = Check sdist post job
    • check-skipped = Check sdist post job
  • any of [🛡 GitHub branch protection]:
    • check-success = Changelogs
    • check-neutral = Changelogs
    • check-skipped = Changelogs

Reason

The merge conditions cannot be satisfied due to failing checks

Failing checks:

Hint

You may have to fix your CI before adding the pull request to the queue again.
If you update this pull request, to fix the CI, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

mergify Bot added a commit that referenced this pull request May 8, 2026
@mergify mergify Bot added dequeued waiting too long automatically set by Mergify to trigger a warning and removed queued labels May 8, 2026
@Mikolaj
Copy link
Copy Markdown
Member

Mikolaj commented May 14, 2026

@sheaf: sadly, it seems there are conflicts with master now.

Adds a how-to guide in the Cabal's user guide.

Changes to the SetupHooks module and Haddocks:

  - Add an usage overview that explains what the various hooks may
    be useful for.
  - Add a worked example for 'dynamicRule' as it is the most complex
    aspect of the API.
  - Unexpose the gnarly 'RuleCommands' constructors, advising usage of
    'staticRule' and 'dynamicRule' instead.
  - Various small tweaks, including additional haddock comments for
    'dynamicRule'.

Fixes #11461
@sheaf
Copy link
Copy Markdown
Collaborator Author

sheaf commented May 15, 2026

@sheaf: sadly, it seems there are conflicts with master now.

That's strange, I rebased just now and there were no conflicts.

@sheaf sheaf removed ready and waiting Mergify is waiting out the cooldown period waiting too long automatically set by Mergify to trigger a warning dequeued labels May 15, 2026
@zlonast
Copy link
Copy Markdown
Collaborator

zlonast commented May 16, 2026

@sheaf This looks like an internet error due to GitHub instability. I think you should restart CI or rebase.

@mergify mergify Bot added the queued label May 16, 2026
@mergify
Copy link
Copy Markdown
Contributor

mergify Bot commented May 16, 2026

Merge Queue Status

This pull request spent 2 hours 32 minutes 40 seconds in the queue, including 1 hour 29 minutes 34 seconds running CI.

Required conditions to merge
  • #approved-reviews-by >= 2 [🛡 GitHub branch protection]
  • #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • #review-threads-unresolved = 0 [🛡 GitHub branch protection]
  • any of [🛡 GitHub branch protection]:
    • check-success = Doctest Cabal
    • check-neutral = Doctest Cabal
    • check-skipped = Doctest Cabal
  • any of [🛡 GitHub branch protection]:
    • check-success = Meta checks
    • check-neutral = Meta checks
    • check-skipped = Meta checks
  • any of [🛡 GitHub branch protection]:
    • check-success = docs/readthedocs.org:cabal
    • check-neutral = docs/readthedocs.org:cabal
    • check-skipped = docs/readthedocs.org:cabal
  • any of [🛡 GitHub branch protection]:
    • check-success = Validate post job
    • check-neutral = Validate post job
    • check-skipped = Validate post job
  • any of [🛡 GitHub branch protection]:
    • check-success = fourmolu
    • check-neutral = fourmolu
    • check-skipped = fourmolu
  • any of [🛡 GitHub branch protection]:
    • check-success = hlint
    • check-neutral = hlint
    • check-skipped = hlint
  • any of [🛡 GitHub branch protection]:
    • check-success = Bootstrap post job
    • check-neutral = Bootstrap post job
    • check-skipped = Bootstrap post job
  • any of [🛡 GitHub branch protection]:
    • check-success = whitespace
    • check-neutral = whitespace
    • check-skipped = whitespace
  • any of [🛡 GitHub branch protection]:
    • check-success = Check sdist post job
    • check-neutral = Check sdist post job
    • check-skipped = Check sdist post job
  • any of [🛡 GitHub branch protection]:
    • check-success = Changelogs
    • check-neutral = Changelogs
    • check-skipped = Changelogs

mergify Bot added a commit that referenced this pull request May 16, 2026
@mergify mergify Bot merged commit 231b81f into master May 17, 2026
162 of 169 checks passed
@mergify mergify Bot deleted the doc-hooks branch May 17, 2026 01:18
@mergify mergify Bot removed the queued label May 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days merge me Tell Mergify Bot to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants