Update Theme Submission Guidelines and README

[onedrawingperday]

We need to make it very clear to theme authors that themes need to be always maintained and that they should not be treated the same as personal projects

• the link to the README needs to be made more prominent in the theme submission template (bold, bigger font or made into the headline etc i.e. Please make sure that you have read and met all theme guidelines before submitting an issue) because I keep seeing submissions with wrong screenshot dimensions, missing theme.toml attributes etc and it is apparent that authors have not read the README.

• mainSections should be used instead of hardcoded sections for rendering lists

• readFile or readDir should not be used in theme layouts templates, as well as no hardcoded PATHs in the form of: {{ .Site.baseURL }}/something either in templates or in the config of an Example Site.

• never leave pages without layouts. Instead use disableKinds. A theme with no layouts for various kinds pollutes the Hugo Themes deploy logs to the point that these are almost unusable

• never use the deprecated .Page.URL instead use .Permalink, .RelPermalink etc

• also I propose that we discourage the use of third party CDNs to serve assets, it is no longer a good practice in this day and age (fingerprinting, security risk etc)

• theme maintenance . If a theme demo breaks with the latest Hugo it will be removed from the Theme Showcase (it is the theme author's obligation to make sure that a theme renders with the latest Hugo)

• keep the theme's Git Repo’s history down. No huge binaries.

• never use photos that are copyrighted. Make sure that your theme’s resources can be used in an Open Source theme

If you agree/disagree with the above points, have suggestions etc please let me know so that I can send a Pull Request to update the README and make its link in the theme submission template more prominent.

Thanks

cc: @digitalcraftsman

[AngeloStavrow]

I have several thoughts around the idea of "theme maintenance" requirements — where would be the best place to have a discussion on this? A separate issue here? A topic on the forums? Thanks!

[onedrawingperday]

@AngeloStavrow
This issue is the best place to post your ideas.

[AngeloStavrow]

Okay, so, this is going to be a bit of a long comment. Maintenance is the hardest part of any project, and I want to be thoughtful about the fact that this affects more than just the theme author, but also the hugoThemes maintainers, and maybe even the maintainers of Hugo itself.

Requiring ongoing theme maintenance of authors that want their theme in the gallery is a good thing. Having great, up-to-date themes in the gallery shows off all the great things that Hugo can do. Broken themes in the gallery are "bad publicity", if you will, for both Hugo and those theme authors.

I imagine that it's also a lot of work to curate the gallery, and at least some of the process seems to be manual, so it's time consuming on top of the time and effort the gallery maintainers put into answering questions from theme authors, both in GitHub and on the support forum. I fully support making their lives easier.

themes need to be always maintained and […] should not be treated the same as personal projects

I agree 100%, but would like to flag something here (that I'm sure you all are probably also thinking about): let's also make sure that theme authors (and everyone in the Hugo community) are set up for success! For example, I looked around and couldn't find documented maintenance or release commitments/processes for either the Hugo or hugoThemes projects, and I feel that those are necessary pre-requisites to a healthy culture of theme maintenance.

All of this preamble raises questions for me that I'd want to ask of theme authors, gallery maintainers, and the Hugo maintainers. I hope they prompt some constructive conversation!

How can theme authors and gallery maintainers prepare for new releases of Hugo?

• Should we aim to have to some -beta or -nightly branch of Hugo that theme authors can test against before releases drop? I couldn't find any such branch in the Hugo repo.
• Should theme authors and gallery maintainers expect a regular release schedule for Hugo?
• Should theme authors expect a regular build schedule for the gallery?
• What's the best way for theme authors, gallery maintainers, and Hugo maintainers to work together on a guidance document for theme maintenance?

What should happen when a theme is broken with the latest version of Hugo?

• Should theme authors expect that a broken theme is removed from the theme gallery immediately?
  • If not, should theme authors expect that there's a grace period of X days where, e.g., their theme is in quarantine and invisible on the gallery until they fix it?
  • If a theme is broken and is removed/quarantined from the gallery, does the author have to go through the full "please add my theme" process?
• Should the gallery build process include some automation to flip a switch between "include this theme" and "don't include this theme" based on some theme.toml metadata?
• Should themes include some metadata in theme.toml like testedForHugoVersion that the gallery build scripts can pick up? How could we define what that means? (In my mind, it should mean that a theme author has confirmed that the theme builds with the version listed.)

[onedrawingperday]

Hello @AngeloStavrow

Below I have tried to answer all of your questions as best as I can:

Should we aim to have to some -beta or -nightly branch of Hugo that theme authors can test against before releases drop? I couldn't find any such branch in the Hugo repo.

Typically one would need to compile Hugo from source to test against new unreleased features. But I understand your point and that is why I am notifying @bep since he is the one who may consider a -beta or -nightly branch for Hugo.

Should theme authors and gallery maintainers expect a regular release schedule for Hugo?

Typically one can follow Hugo's release cycle by having a look at its milestones. Most of the time the milestones' due dates are honored but sometimes there is a delay. It all depends on the workload of the maintainer and the other contributors.

Should theme authors expect a regular build schedule for the gallery?

Due to #259 the schedule is manual and usually it happens about once a week by @digitalcraftsman but there may be a delay.

What's the best way for theme authors, gallery maintainers, and Hugo maintainers to work together on a guidance document for theme maintenance?

The section regarding theme maintenance will be part of the updated README. Once I put the new version together, I will submit a Pull Request and ask for reviews by other members of the Hugo team. I may also ask for your feedback also.

Should theme authors expect that a broken theme is removed from the theme gallery immediately?

Yes. The days of opening issues in theme repos are over. Unless someone else is willing to come forward and invest the time.

If a theme is broken and is removed/quarantined from the gallery, does the author have to go through the full "please add my theme" process?

Yes. Theme authors will have to re-submit a removed theme -once it is updated- for a new review.

Should the gallery build process include some automation to flip a switch between "include this theme" and "don't include this theme" based on some theme.toml metadata?

We already have a few arrays in the Build Script such as noDemo for themes whose demo cannot be rendered or blacklist for themes even though are present in the repo are not published in the showcase for various reasons. However adding a theme to these arrays is manual and is done if there is a good reason for doing so.

Should themes include some metadata in theme.toml like testedForHugoVersion that the gallery build scripts can pick up? How could we define what that means? (In my mind, it should mean that a theme author has confirmed that the theme builds with the version listed.)

We have the min_version attribute in theme.toml which indicates the minimum working version with which a theme functions. The Hugo Themes website always uses the latest Hugo release so a theme is always tested vs the new Hugo versions. If a theme demo breaks then this means that a theme is no longer functional with the latest Hugo.