WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 4 years ago

#35417 closed defect (bug) (fixed)

Audit "blog" usage in inline docs

Reported by: ericlewis Owned by:
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: Networks and Sites Keywords:
Focuses: docs, multisite Cc:
PR Number:

Description

The term "site" is preferred to the term "blog" at this point, so we can update the docs accordingly.

There are plenty of functions and class properties that use the term blog or site. In some cases it may make sense to leave the wording as is, depending on context.

Attachments (3)

35417.diff (21.7 KB) - added by ericlewis 4 years ago.
35417.2.diff (20.7 KB) - added by ericlewis 4 years ago.
35417.3.diff (5.0 KB) - added by ericlewis 4 years ago.

Download all attachments as: .zip

Change History (23)

#1 @ericlewis
4 years ago

  • Component changed from General to Networks and Sites
  • Focuses docs multisite added
  • Keywords needs-patch added
  • Milestone changed from Awaiting Review to 4.5

This ticket was mentioned in Slack in #core-multisite by eric. View the logs.


4 years ago

#3 @ericlewis
4 years ago

  • Keywords good-first-bug added

Marking this as good-first-bug, as it's straight-forward to someone who understands our terminology ("blog" was used for functions that have to do with what we now call a site, "site" was used for functions that have to do with what we now call a network).

#4 @mrahmadawais
4 years ago

@ericlewis Count me in for that. Just for the clarification are we going to consider the single install Site instead of Blog?

#5 follow-up: @ericlewis
4 years ago

@mrahmadawais Yep! A site is a single site. It may have a blog, it may not.

#6 in reply to: ↑ 5 ; follow-up: @mrahmadawais
4 years ago

Replying to ericlewis:

@mrahmadawais Yep! A site is a single site. It may have a blog, it may not.

Couldn't agree more. Where do you think I should start from. I think, we should do it file by file and create separate tickets for each. That way it would be more manageable and smaller goals would lead to a gradual change of documentation. Just like we handle accessibility changes. But I am open to suggestions. What's say?

#7 in reply to: ↑ 6 ; follow-up: @ericlewis
4 years ago

Replying to mrahmadawais:

Couldn't agree more. Where do you think I should start from. I think, we should do it file by file and create separate tickets for each.

A cursory search tells me there's about ~700 hits for "blog" within a PHP inline comment. A lot of these are false positives, as they are explicit variable names in @param docs (e.g. $blog_id) which of course we will leave.

Let's try putting together a single patch on this ticket and break it up if that gets overwhelming.

Have at it! :D

#8 in reply to: ↑ 7 @mrahmadawais
4 years ago

Replying to ericlewis:

Let's try putting together a single patch on this ticket and break it up if that gets overwhelming.
Have at it! :D

Let's do that. I am going to start tonight :)

#9 @mrahmadawais
4 years ago

@ericlewis Do you have an example file for me? I have started looking into it, but most of the inline docs are about defining a particular argument that also contains a blog related name.

E.g. https://i.imgur.com/ef1s0B9.png

So, could you show me an example of where we can change it, so, that I could have a better idea about this one.

#10 follow-up: @ericlewis
4 years ago

Replying to @mrahmadawais:

most of the inline docs are about defining a particular argument that also contains a blog related name.

In this case, I think it would be useful to change the description for $blog_title to The new site title, so that the misleading naming is within variable naming, not the documentation.

I would suggest doing a regular expression search on all php files in the codebase like this: \*.*[^\$]blog. This will give you any lines that are inline documentation with the word blog. It will avoid places where $ is prepended to blog, avoid false-positives for variable names that aren't of interest to us.

Now it looks like there are about 587 matches. I think your previous thought regarding new tickets for new files would be a good idea at this point, that's a lot of fixes to make!

I've created #35589 as a break-out ticket to focus on the file wp-includes/link-template.php. Would you like to try that? :D

Last edited 4 years ago by ericlewis (previous) (diff)

#11 in reply to: ↑ 10 @mrahmadawais
4 years ago

Replying to ericlewis:

Replying to @mrahmadawais:

most of the inline docs are about defining a particular argument that also contains a blog related name.

In this case, I think it would be useful to change the description for $blog_title to The new site title, so that the misleading naming is within variable naming, not the documentation.

I would suggest doing a regular expression search on all php files in the codebase like this: \*.*[^\$]blog. This will give you any lines that are inline documentation with the word blog. It will avoid places where $ is prepended to blog, avoid false-positives for variable names that aren't of interest to us.

Thanks for that. Makes sense.

Now it looks like there are about 587 matches. I think your previous thought regarding new tickets for new files would be a good idea at this point, that's a lot of fixes to make!

I've created #35589 as a break-out ticket to focus on the file wp-includes/link-template.php. Would you like to try that? :D

Yes, that's what I was talking about. Let's try that way.

#12 follow-up: @ericlewis
4 years ago

Not sure what to do about this:

That's all, stop editing. Happy blogging!

Probably out of scope of this ticket.

@ericlewis
4 years ago

@ericlewis
4 years ago

#13 in reply to: ↑ 12 @mrahmadawais
4 years ago

Replying to ericlewis:

Not sure what to do about this:

That's all, stop editing. Happy blogging!

Probably out of scope of this ticket.

We could remove "Happy blogging!" phrase.

#14 @ericlewis
4 years ago

  • Keywords has-patch added; needs-patch good-first-bug removed

#15 @jeremyfelt
4 years ago

Splitting hairs, but For setups that use the multi-site feature. Can be used outside of the multi-site feature. in wp-includes/deprecated.php can probably be multisite vs multi-site for consistency.

Last edited 4 years ago by jeremyfelt (previous) (diff)

#16 @ericlewis
4 years ago

In 36416:

Networks and sites: Replace "blog" usage with "site" in docs.

Multisite functions use the term "blog" to refer to what we now call a "site," e.g. get_current_blog_id(). These functions are here to stay because of our commitment to backwards compatibility. What we can do is set the documentation straight.

See #35417.

@ericlewis
4 years ago

#17 @ericlewis
4 years ago

In 36417:

Networks and sites: Replace "blog" usage with "site" in docs.

Multisite functions use the term "blog" to refer to what we now call a "site," e.g. get_current_blog_id(). These functions are here to stay because of our commitment to backwards compatibility. What we can do is set the documentation straight.

See #35417.

#18 follow-up: @ericlewis
4 years ago

  • Keywords dev-feedback added; has-patch removed

I've removed the good-first-bug because I think some hard decisions need to be made with some of what's left.

Should we call $wpdb->blogid Site ID? Multisite "sites" table? site prefix?

Similarly in the caching API, e.g. referring to "blog cache groups". Should these be site cache groups?

I ask because some of these terms are so ingrained in our nomenclature. I'm leaning towards changing all of them, which will hopefully change the vocabulary we use. e.g. I think "site prefix" is a more usable term than "blog prefix."

#19 in reply to: ↑ 18 ; follow-up: @DrewAPicture
4 years ago

Replying to ericlewis:

I've removed the good-first-bug because I think some hard decisions need to be made with some of what's left.

Should we call $wpdb->blogid Site ID? Multisite "sites" table? site prefix?

Similarly in the caching API, e.g. referring to "blog cache groups". Should these be site cache groups?

I ask because some of these terms are so ingrained in our nomenclature. I'm leaning towards changing all of them, which will hopefully change the vocabulary we use. e.g. I think "site prefix" is a more usable term than "blog prefix."

I think changing the above just to change them for consistency isn't a great reason. As you cited, the nomenclature is pretty ingrained at this point.

Either way, I think the spirit of the ticket has been fulfilled. If you don't think so, feel free to punt to future release.

#20 in reply to: ↑ 19 @ericlewis
4 years ago

  • Keywords dev-feedback removed
  • Resolution set to fixed
  • Status changed from new to closed

Replying to DrewAPicture:

Either way, I think the spirit of the ticket has been fulfilled. If you don't think so, feel free to punt to future release.

Cool, let's close. We've got a lot done here and can always open a new ticket later.

Note: See TracTickets for help on using tickets.