search

Automattic / _s

Hi. I'm a starter theme called _s, or underscores, if you like. I'm a theme meant for hacking so don't use me as a Parent Theme. Instead try turning me into the next, most awesome, WordPress theme out there. That's what I'm here for.
http://underscores.me/
GNU General Public License v2.0
10.96k stars 3.12k forks source link

Improve documentation #1387

Closed carolinan closed 4 years ago

carolinan commented 4 years ago

A problem we see when authors submit themes based on underscores to WordPress.org, is that the author does not know or understand that they have to update files and remove unused files.

The documentation about how to best use this starter theme needs to be improved and extended.

Every week, the theme's team has to sort out copies of underscores where the users has added no additional styles, and no screenshot. Sometimes, it is just spam.

Other times, the author adds a minimal amount of styles, but forgets to update: theme and author URI readme.txt and readme.md theme description and tags footer credits language file layouts folder (which is not used by 99% of the theme copies) rtl.css (which is commented out)

It is bad enough that we have had to prepare automated checks to block these themes.

ianstewart commented 4 years ago

If a themer is adapting _s without paying attention to updating the list of things above (especially the screenshot!) I'm not sure if they're the sort to read documentation carefully either. :)

That said, it might not hurt to add a "Are you new to making WordPress themes? Do you want to share your creation at https://wordpress.org/themes/ ?" Don't forget to update and review the following items:" PRs welcome! Shorter is better to start.

hanneslsm commented 4 years ago

Shorter is better to start.

How about a simple checklist?

If you want to publish this theme, please…
- [ ] Update the theme and author URI in the styles.css
- [ ] Update your readme.md with relevant information for users and developers
…
ianstewart commented 4 years ago

That could work. It'd be fun if it ended with …

- [ ] Share it with the world https://wordpress.org/themes/upload/

Might not need to be an actual checklist with square brackets.

carolinan commented 4 years ago

Please don't do that... It is difficult to be both encouraging and sceptical ;)

philiparthurmoore commented 4 years ago

Is there a way to tackle this from both ends? If someone is using _s to develop a theme for WordPress.org, it ultimately falls on WordPress.org to state its guidelines clearly for theme submissions. The purpose of _s is to be a starter theme for pretty much anyone, not necessarily .org, so I'm wondering how this would work well in practice without compromising _s' ability to iterate.

I don't see anything here or here related to _s. It may be worth improving the .org documentation (where theme submissions come in) rather than the repo itself because of some developers simply using the code barebones without thinking about requirements for mass production.

(I do agree that better documentation is always a good thing!)

carolinan commented 4 years ago

No there are no requirements specific for one starter theme, Underscores or any other.

There are requirements for the readme files, the screenshot, theme URI, author URI, and the footer credit links. They apply to all submitted themes.

The language file is expected to be for the correct, current theme, if it is included at all. Is that something you feel theme authors would benefit from, if we added it to the requirements.

Unused files are expected to be removed, but it is not something that the review team enforces. (Unless we are being asked to review large amounts of code that is unused and irrelevant).

We sometimes ask authors if they intended to use the rtl file, and why it is commented out. So that they can update it or remove it.

Ismail-elkorchi commented 4 years ago

I have made some changes that seeks to address some of those problems :

Lastly, I created https://github.com/Automattic/_s/pull/1419 to add instructions to use these commands in README.md, but I need some eyes on this PR to make sure that nothing is missing . Any suggestions or feedback would be much appreciated.