Audit "blog" usage in inline docs

[ericlewis]

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.

[ericlewis]

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).

[mrahmadawais]

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

[ericlewis]

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

[mrahmadawais]

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?

[ericlewis]

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

[mrahmadawais]

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 :)

[mrahmadawais]

@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.

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

[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.

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

[mrahmadawais]

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.

[ericlewis]

Not sure what to do about ​this:

That's all, stop editing. Happy blogging!

Probably out of scope of this ticket.

[mrahmadawais]

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.

[jeremyfelt]

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

[ericlewis]

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]

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.

[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."

[DrewAPicture]

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.

[ericlewis]

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.