TODO-list for "getting ready for release"

bep commented 9 years ago

In stead of creating a lot of small tasks in separate issues, lets try to agree on a more compact list here.

[x] add scripting for theme-specific params. A template file with key-values that the script can append to the config.toml should do. Also think about how to get the param-specific images (banner, logo etc.) into the example site. (@bep)
[x] handle mismatch of sections used in the different themes (post vs blog etc.); a symbolic link or two would be tempting, but I don't think that would work. not sure this is a problem
[x] Update README on hugoThemes about custom exampleSite @bep
[x] Rename examples to exampleSite in @digitalcraftsman sites where applicable
[x] Modify script to handle exampleSite if it exists in a theme @bep
[x] blacklist themes that doesn't follow "the standard" and breaks the site. Open up pull requests for changes needed. Do not work around readme.md vs README.mdetc. -- get the themes to be uniform. Much easier in the long run.
[x] Walk through the themes one by one and apply the fixes above (params, section mismatch etc.)
[x] Images that aren't linked to the "raw" version in the READMEs will not be shown

/cc @digitalcraftsman

bep commented 9 years ago

Lets agree on "what is really needed for the first version". Deployment is easy, so focus on the big picture, get it in a working state, then we can add pagination, filters etc. in the next version.

digitalcraftsman commented 9 years ago

I agree that we should focus our work on the core problems that you listed above.

Adding key-value pairs could cause problems, if two themes use the same key with different values. If you make them somehow theme-specific (with the theme name as prefix for example) could the keys probably not be found be the theme, because the orignal key-name isn't used anymore.
I think the question of wether blog or post should be used limits the freedom of the user to choose his own url/file scheme. Beside thatm, what do you exactly mean with a symbolic link?
Sure, themes should follow standardized rules that are obligatory for the themes, if they want to be added to the theme gallery. What rules do you think should be added? For a uniform name of the readmes I would use the uppercase version README.md, because most themes (and repos in general) use this format as far as I've seen it on Github.
Walking through each theme will take a lot of time, since probably not every theme maintainer will merge the pull requests directly. But it's the best way to go. I've seen in the forum of Hugo that you created a list of themes that require fixes. Is it still up to date?

bep commented 9 years ago

Let us face that problem if it is a problem. In my head, the params we would want to fill in is description, author, logo, slogan, banner etc. -- I have hard time seeing any problems in these areas.
Sure, but it's kind of outside of the scope of this task... maybe ... I'm not sure how to fix it, either -- making "post" the standard section, maybe? With symbolic link i meant a link from /post > /blog or whatever, so the content would be duplicated. But it is a stupid idea.
Lets take the problems one by one. I do not think there are many readme.md vs README.md and similar left.
Sure, it is boring work. But it can be done pretty snappy if you use hub (a command line tool from GitHub). My list is out of date. That was something I did to get the very basics in line, getting all the theme.toml files in line etc. And many themes has arrived since.

If we both can have a look at a couple of the themes that doesn't work nicely in demo mode, and think a little bit about what would be needed to change, then we can discuss a game plan -- create a list and split the work.

bep commented 9 years ago

Re. post vs blog, it doesn't seem to bee an issue, if my search is correct:

find . -name "index.html" | grep layouts | xargs grep 'where'
./angels-ladder/layouts/index.html:  {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
./angels-ladder/layouts/index.html:  {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
./beg/layouts/index.html:            {{ range first 10 (where .Data.Pages "Type" "post") }}
./bootie-docs/layouts/index.html:{{ range where .Site.Pages "Title" "_index" }}
./casper/layouts/index.html:    {{ $paginator := .Paginate (where .Data.Pages "Section" "post") }}
./greyshade/layouts/index.html:                 {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
./hurock/layouts/index.html:    {{ range first 5 (where .Site.Pages "Section" "links") }}
./hurock/layouts/index.html:    {{ range first 10 (where .Site.Pages "Section" "posts") }}
./hyde-x/layouts/index.html:    {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
./next/layouts/index.html:{{ $paginator := .Paginate (where .Data.Pages "Type" "post") .Site.Params.perPage }}
./persona/layouts/index.html:              {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
./pixyll/layouts/index.html:                        {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
./shiori/layouts/index.html:      <a href="{{ .Site.BaseURL }}/post" class="btn btn-primary btn-block btn-lg">View All {{ len (where .Site.Pages "Section" "post") }} Articles →</a>
./slim/layouts/index.html:        {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }} {{ range $paginator.Pages }}
./startbootstrap-clean-blog/layouts/index.html:          {{ range first 4 (where .Data.Pages "Type" "post") }}
./twentyfourteen/layouts/index.html:            {{ range first 10 (where .Data.Pages "Section" "post") }}

digitalcraftsman commented 9 years ago

Would it be possible to let generateThemeSite.sh output error messages during the generation of the site? This would it make much easier to locate possible issues that could be added to the list.

Furthermore, what would be a good tool to manage this list? Should we use simple Github repository or somethink like your table made in Google Docs?

And what themes should be added to the blacklist? Some have only trivial problems like missing screenshots and others are simply incompatible with a current version of Hugo that we use to generate the theme gallery.

bep commented 9 years ago

./generateThemeSite.sh http://localhost:1313 && hugo server -s hugoThemeSite/themeSite is the level of error reports you will ever get.

A Google spreadsheet is good for this, lets use this one:

https://docs.google.com/spreadsheets/d/1QNdevhMM9M0ba5Y00sJ6GIbtyR4svb37hc2JsHCVgiU/edit?usp=sharing

Just add new columns as needed. But be pragmatic when checking a theme, think "good enough".

Blacklist = breaking change, generateThemeSite.sh fails or the theme cannot be rendered / demo shown. It is only temporary. Attach a PR reference near the blacklist. But this is mostly relevant when we go live. While in progress it is OK with some breaking sites.

I can start with adding some script support for custom params for the themes -- then we can split the themes between us. Many of them is, hopefully, just to check that it rendered OK.

Sounds like a plan?

digitalcraftsman commented 9 years ago

This sounds good. Hopefully we will finish it soon. But some pull requests will take time.

bep commented 9 years ago

I'm not conviced there will be many pull requests, but time will show ...

I notice some of your themes have some complex data dependencies (agency, artists) that doesn't fit well into this scheme ...

digitalcraftsman commented 9 years ago

Do you mean the files that need to be copied from examples?

bep commented 9 years ago

Yes, I think we need to make some standard about that one, too.

Most themes follow a simple post + page section layout that we can use the exampleSite for. Then there is agency, artists ... where we need to pick up the example from the theme itself.

Your setup is good, but I would name it exampleSite (to be in line with the other exampleSite).

So the logic will be something like:

If the theme contains a exampleSite folder, use that for the demo.
else, use the standard exampleSite

Sounds good?

digitalcraftsman commented 9 years ago

Maybe we should create a list with requirements named CONTRIBUTING.md that explains, what require to be standard. If those requirements are defined I'll begin to adapt them to my themes.

bep commented 9 years ago

There is already a standard in the README.md. in hugoThemes. We will append to that one as needed.

But this can get complex ... and thinking about it, I'm not too keen on letting the theme authors control content on the hugoThemeSite. Let me sleep on that.

digitalcraftsman commented 9 years ago

This could be indeed a problem. But do you know a workaround for themes that require custom data in order to work (like my themes)?

bep commented 9 years ago

Will think about it.

bep commented 9 years ago

One could argue that the theme authors already got some control of the content through the README.md

@spf13 what do you think about this? Short story: Some themes are so complex that they provide their own exampleSite. Is this OK or bad in the sense that it gives them control over the content on hugoThemeSite?

spf13 commented 9 years ago

I think it's ok.. but maybe a v2 thing. Reality is that some themes will need their own content to convey their purpose.

spf13 commented 9 years ago

I also think we should take the approach of trusting our theme creators and remove them if they don't play nice.

bep commented 9 years ago

OK, then we have a good game plan.

@digitalcraftsman I will update the README.md on hugoThemes with this new information. Can you do the renaming of "examples" to "exampleSite" in your themes where applicable? Then in v1 we can at least make sure that your themes look good, then others with similar needs can use them as guides.

bep commented 9 years ago

@digitalcraftsman I have added some initial config support in the script ++. More work to do here (there are conflicts that must be fixed). But now Casper looks good.

To fail fast in the script, look at

https://github.com/spf13/hugoThemeSiteScript/blob/master/generateThemeSite.sh#L10

bep commented 9 years ago

@digitalcraftsman see https://github.com/spf13/hugoThemesSite (the README) for info about how to add theme specific config. We should aim for the least amount of files possible here -- if it gets too complex, then a theme should create its own exampleSite.

bep commented 9 years ago

@digitalcraftsman and note: the ERRORs about URL and sageHTML etc: I have already created PRs for all of these. It just take some time to get them merged.

digitalcraftsman commented 9 years ago

@spf13 We could also add an option to report and flag themes by the visitors in the case of an abuse.

digitalcraftsman commented 9 years ago

I renamed the folders in my themes to exampleSite.

digitalcraftsman commented 9 years ago

@spf13 I would even encourage maintainers to add some (dummy) content to the exampleSite folder. Otherwise is a demo of a blog, where you can't see a rendered post, not really a demo.

bep commented 9 years ago

Work in progress site preview:

http://185.52.0.94:1313/

Maybe some border/divider of some sort would be good on the front page?

spf13 commented 9 years ago

This is looking really good. Thanks @bep !

dplesca commented 9 years ago

@bep Something like this would be ok? http://i.imgur.com/LqE444b.png

bep commented 9 years ago

@dplesca that would be perfect!

dplesca commented 9 years ago

I've just pushed a change with that border.

bep commented 9 years ago

@dplesca there is a border, but it doesn't look like the screenshot you posted:

http://185.52.0.94:1313/

dplesca commented 9 years ago

@bep what are you using, it looks ok to me, I'm on Chrome on Windows.

bep commented 9 years ago

@dplesca I'm currently on OSX (love, hate). It looks good in Safari -- kind of ugly in Firefox:

dplesca commented 9 years ago

It looks atrocious in firefox, let me see what I can do.

edit: @bep just pushed another tiny change

bep commented 9 years ago

@dplesca yea, now it looks great in both Safari and Firefox (OSX). Thanks!

http://185.52.0.94:1313/

digitalcraftsman commented 9 years ago

@spf13 One of the themes that would need to be updated is your port of Hyde. There are already PRs made (some from me) to make the theme compatible with newer Hugo versions. It doesn't seem that you maintain this repo actively because some commits are a bit older. Therefore @bep or I as collaborators could merge those PRs and make other changes (if necessary).

The same applies to the Herring Cove theme where @bep made a PR.

spf13 commented 9 years ago

Those were the first two themes for Hugo largely to demonstrate how to make themes. As I don't use either, I'd be happy to have others help maintain them. Adding you both now..

bep commented 9 years ago

I think it looks good enough for a release now:

http://185.52.0.94:1313/

There are open pull requests, but nothing blocking. If we can get some simple deployment in place, we can fix these in the upcoming releases.

/cc @digitalcraftsman @spf13

digitalcraftsman commented 9 years ago

@bep That's true. Most PRs are only for trivial fixes. Since the todo list above seems to be done we should be ready to deploy. Is there already something planned, when the theme gallery will be running under themes.gohugo.io?

bep commented 9 years ago

@spf13 would have to help us get this over the finish line. I guess there will be regular updates to this site, to a "one click deployment" kind of thing would be needed. I don't think it can be connected to a Git commit, either, because there are three GitHub repos in play ... But I might be wrong.

bep commented 9 years ago

@spf13 any clue on when this could happen? It's no rush, but good to have some sense of time.

digitalcraftsman commented 9 years ago

It would be interesting to know who this project will progress.

bep commented 9 years ago

@digitalcraftsman ditto. @spf13 will get to it, eventually; the site is ready and I guess we will see a boost in Hugo activity once released.

bep commented 9 years ago

Closing this. It is finished, but may be outdated the distant day in the future the site gets online.

gohugoio / hugoThemesSite

TODO-list for "getting ready for release" #16