Skip to content

Docs: Improve scoping of two potentially overlapping Triage sections #9302

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

Merged
merged 1 commit into from
Jun 15, 2022

Conversation

benjaoming
Copy link
Contributor

@benjaoming benjaoming commented Jun 7, 2022

  • Improve the scope of the two Triaging sections
  • Fixes wrong :doc:`team` referencing Write the Docs via intersphinx
  • This is a bit meta-level: Since I'm going over dev docs right now, I wonder how exactly this PR lands: It's a PR without an issue, so it's not actually triaged. Some projects prefer that an issue is always opened for discussion, some prefer that contributors have a shortcut by simply opening a PR. I believe that this is resolved, we keep things as they are, adding a bit more incentives on the triaging process.
  • Do not allow any :doc: or :ref: to resolve to intersphinx mapping without :external: prefix
  • Ignore :external: role in rstcheck

@benjaoming benjaoming added the Priority: low Low priority label Jun 7, 2022
@benjaoming benjaoming force-pushed the triaging branch 2 times, most recently from 76daf5f to dd1de34 Compare June 8, 2022 11:59
@benjaoming benjaoming mentioned this pull request Jun 8, 2022
@benjaoming benjaoming marked this pull request as ready for review June 14, 2022 10:44
@benjaoming benjaoming requested a review from a team as a code owner June 14, 2022 10:44
@benjaoming benjaoming requested a review from ericholscher June 14, 2022 10:44
@benjaoming benjaoming requested review from humitos and stsewd June 14, 2022 13:01
@benjaoming
Copy link
Contributor Author

It seems these two warnings are new

/home/circleci/project/docs/user/localization.rst:52: WARNING: unknown document: custom_domains
/home/circleci/project/docs/user/single_version.rst:28: WARNING: undefined label: custom_domains:canonical urls

Probably used to be resolved via intersphinx... will have a look...

@benjaoming benjaoming requested a review from a team as a code owner June 14, 2022 13:34
…ped resources, fix cross-references, update Triage sections intro/scope
Copy link
Member

@humitos humitos 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 to me 👍🏼

One comment. Please, do not force push new commits if there is a review already done in the PR because that forces the reviewers to review all the files again since GitHub interprets as all the content is new. If there is a way to solve this problem involving force push I'm happy to know how, but I didn't find it. If you want to rebase/change history/etc you can do that immediately before merging the PR

@benjaoming benjaoming merged commit 272121e into readthedocs:main Jun 15, 2022
@benjaoming benjaoming deleted the triaging branch June 15, 2022 15:10
@benjaoming benjaoming changed the title Improve scoping of two potentially overlapping Triage sections Docs: Improve scoping of two potentially overlapping Triage sections Jun 15, 2022
@benjaoming
Copy link
Contributor Author

benjaoming commented Jun 15, 2022

Please, do not force push new commits if there is a review already done in the PR because

This is done so that I - as a PR Author - can ensure that the commit history is nice and clean before a merge. There are several alternatives to the same goal:

  1. A maintainer asks the PR Author to rewrite the commit history
  2. A maintainer chooses squash/rebase and the branch is rewritten before a merge -- but without any manual choices or interventions
  3. Author uses the !fixup notation from the beginning -- I think in this case, it will be quite explicit for the maintainer that a squash is expected before a final merge. Github.com doesn't support anything out of the box for this yet
  4. A rewrite on the author's initiative (what I just did) - the author rewrites the history themselves in anticipation of a merge. This can be done repeatedly, but should be avoided when there are open reviews - it should especially also be avoided if others are using the PR branch.

Of course, there is also the option of keeping all the commits and merging the classic way.

that forces the reviewers to review all the files again since GitHub interprets as all the content is new.

This is not really true, you can see all comments and what segments of the code they belong to. All comments in this PR were outdated.

Personally, I like to take a pragmatic approach and not see any of these as a mandatory option, as it raises the bar for contribution and makes it too easy for developers to have discussions 😄

@humitos
Copy link
Member

humitos commented Jun 15, 2022

@benjaoming

that forces the reviewers to review all the files again since GitHub interprets as all the content is new.

This is not really true, you can see all comments and what segments of the code they belong to. All comments in this PR were outdated.

I'm not talking about the comments, but the changes themselves. If you force push, when I go to "File changed" tab, GitHub shows me all the files again, instead of only the last changes since I reviewed this PR last time. So, I lost all the files I marked as "Viewed" and I'm not sure what changes from the last time I review the PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Priority: low Low priority
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants