Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make documentation @api private by default. #16831

Merged
merged 1 commit into from
Apr 26, 2024

Conversation

reitermarkus
Copy link
Member

@reitermarkus reitermarkus commented Mar 6, 2024

  • Have you followed the guidelines in our Contributing document?
  • Have you checked to ensure there aren't other open Pull Requests for the same change?
  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your changes? Here's an example.
  • Have you successfully run brew style with your changes locally?
  • Have you successfully run brew typecheck with your changes locally?
  • Have you successfully run brew tests with your changes locally?

Our API is mostly private, so make anything that is unmarked @api private by default.

I added a brew rubydoc --open command to view docs locally.

@Homebrew/maintainers, please check if you find anything that is currently unmarked but used outside of this repo, and add the following accordingly:

  • @api public: Usable in formulae/casks, or by third-party taps.
  • @api internal: Usable by official taps.
  • @api private: Usable in Homebrew/brew.
  • @private: Only used for things that can't be made private.

Copy link
Member

@MikeMcQuaid MikeMcQuaid left a comment

Choose a reason for hiding this comment

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

Love this idea!

@api public: Usable in formulae/casks, or by third-party taps.
@api internal: Usable by official taps.
@api private: Usable in Homebrew/brew.
@Private: Only used for things that can't be made private.

Would be great to explicitly document this somewhere.

I realise this is probably actively impossible but: would be great to figure out if this is enforceable at all through checks, too.

Copy link

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

@github-actions github-actions bot added the stale No recent activity label Apr 12, 2024
@github-actions github-actions bot closed this Apr 20, 2024
@MikeMcQuaid
Copy link
Member

@reitermarkus Would love you to rebase this and we can get it merged when you get a bit!

Copy link
Member

@MikeMcQuaid MikeMcQuaid left a comment

Choose a reason for hiding this comment

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

Good to merge when you are 👍🏻

@reitermarkus reitermarkus removed the stale No recent activity label Apr 26, 2024
@@ -4,8 +4,6 @@
require "dependable"

# A dependency on another Homebrew formula.
#
# @api private
class Dependency
Copy link
Member

Choose a reason for hiding this comment

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

This class is used in Homebrew/test-bot, I believe.

Copy link
Member Author

Choose a reason for hiding this comment

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

Couln't find it in test-bot.

Copy link
Member

Choose a reason for hiding this comment

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

Library/Homebrew/development_tools.rb Show resolved Hide resolved
Library/Homebrew/extend/ENV/super.rb Show resolved Hide resolved
Library/Homebrew/formula_versions.rb Show resolved Hide resolved
@reitermarkus reitermarkus force-pushed the docs-private-by-default branch 6 times, most recently from b6a1964 to 1839f86 Compare April 26, 2024 16:39
@reitermarkus reitermarkus marked this pull request as ready for review April 26, 2024 16:39
Copy link
Member

@MikeMcQuaid MikeMcQuaid left a comment

Choose a reason for hiding this comment

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

Looks good! I'm sure we'll need to adjust some of this over time but let's get it merged ASAP to avoid conflicts. Great work @reitermarkus!

@MikeMcQuaid MikeMcQuaid merged commit 5607487 into Homebrew:master Apr 26, 2024
33 checks passed
@github-actions github-actions bot added the outdated PR was locked due to age label May 27, 2024
@github-actions github-actions bot locked as resolved and limited conversation to collaborators May 27, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
outdated PR was locked due to age
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants