Unreleased features warnings on site

[parkr]

This allows us to introduce changes to the site without barring us from always being able to publish it. 🤘 Fixes #1964.

( @cobyism, there's probably a better color or unicode character, but this is what I have for now. Thoughts? )

Gradient generated via http://www.colorzilla.com/gradient-editor/, unicode character courtesy of the PDFs on http://www.unicode.org/charts/#symbols

[troyswanson]

Nicely done. I did a bit of tweaking and think the following looks a bit nicer for the icon:

.unreleased:after {
  content: "⚒";
  color: #ffe9c3;
  position: absolute;
  top: 8px;
  left: 14px;
  font-size: 38px;
  font-weight: bold;
  text-shadow: 0 -1px 0 rgba(0,0,0,.5);
}

[parkr]

What do you prefer about the lighter version? Not sure we get much from it.

[troyswanson]

I think if you want to maintain consistency with the other note ribbons (namely, keep the -1px text shadow), it should be a light color. It seems unnatural for anything to have a shadow behind it while still having a dark face.

[parkr]

Fair enough! Pushed :)

[troyswanson]

I assume once this is merged, you will deploy the site?

[parkr]

@troyswanson Probably! Just need @mattr-'s 👀 and would love @benbalter's 🧠

[troyswanson]

Probably!

In that case, I believe there should be some kind of instructions on how to install said alpha release.

[parkr]

In that case, I believe there should be some kind of instructions on how to install said alpha release.

I was thinking about a "Prereleases" page or something. We could alternatively include it on the Installation page. Thoughts?

[troyswanson]

Installation page seems right. Between the "Install with RubyGems" and "Optional Extras" sections.

It would probably be beneficial to include instructions on how to build the project from the repo itself, as well as installing a --pre version of the gem.

[benbalter]

What's the value in specifying the exact development build? I'd rather allow site on master to be always publishable as #1964 says, not publishable so long as we've pushed a release.

Why not swap out "version foo", which would have to be bumped across every doc, e.g., when we release RC2 (or RC17), for "latest development version" with a link to a download, or instructions on how to run trunk.

That way, pull requests can be code + tests + docs, and at any given time, we can publish the site, and it would always represent the latest and greatest bleeding edge Jekyll has to offer (and hopefully encourage more people to test it prior to release).

Edit: I'd also make it an include, potentially with the version as an argument. We'd also want to add instructions to CONTRIBUTING.md with how to document features for pull requests.

Edit2: I'd also make it clear that obscure version name is really a bleeding edge, not polished version, and should not be run in production (which is another reason I like the "development version" approach).

[parkr]

What's the value in specifying the exact development build?

You mean my reference to 2.0.0.alpha.1? Just for transparency's sake. If I know I want the feature, I can go gem install jekyll -v 2.0.0.alpha.1 because the comment is there. We can tailor the message for other situations in which there is no alpha release – why not be transparent about this now? We can also specify a site.development_version, but that doesn't factor in removal of features nor is it a minimum version.

Why not swap out "version foo", which would have to be bumped across every doc, e.g., when we release RC2 (or RC17), for "latest development version" with a link to a download, or instructions on how to run trunk.

So you're saying instead of specifying the minimum version, I should just say "this is not released yet but it's in a pre-release version. Install it using COMMAND." It's not very specific and doesn't give us much freedom to rip features out of a release if we decide we don't want them. If a version is in alpha.1 but not alpha.2 then the user will be severely confused and most of our users aren't Ruby programmers, near as I can tell, so they won't know to look at the code for their feature.

[mattr-]

I'd also prefer less specific wording around what version the feature could be found in. I think it makes a ton of sense to put together some docs on how to install the master version of Jekyll and link to them from this little notice here. I can imagine it would be very similar to the instructions we already have now for installing from gems. Sadly, I don't have the bandwidth to add this new page with instructions right now, but if this PR is still around when I do have the bandwidth, then I'll be happy to write something up.

It's not very specific and doesn't give us much freedom to rip features out of a release if we decide we don't want them.

Being less specific works in our favor if we do rip out something that was pushed to master but not released. If we remove a never-released feature, then we should also be removing the docs from the site at the same time. If people actually remember the feature and ask where it went, then we just answer the question, close their issue, and move on. No big deal. 😃

[cobyism]

@parkr @troyswanson I think this new note type looks fine to me 👍.

It seems unnatural for anything to have a shadow behind it while still having a dark face.

It’s a moot point now that the color has been changed to a light icon, but the way to make it look inset (and consistent with the other note styles) with a dark face would be to change the shadow to instead be a 1 pixel downwards transparent white one (e.g. 0 1px 0 rgba(255,255,255,.25)). For example:

[cobyism]

I’m wondering if it wouldn’t be better to just make this a more generic heading, rather than listing out all the possible note types. For example, could this just be "Things to watch out for" or "Helpful hints" or something? That way if these note types change again in the future the heading doesn’t have to be updated.

Also orphaned words kill my inner typography nerd, and a shorter heading would help this too:

[troyswanson]

Agreed on coming up with a better heading for this section.

[parkr]

Something shorter is definitely warranted! I was trying to find the antonym of "releases" but just couldn't so I got what we have above 😺

I like "Helpful hints"!

[mattr-]

orphaned words kill my inner typography nerd

poor nerd.

👍 to "Helpful Hints"

[troyswanson]

It’s a moot point now that the color has been changed to a light icon, but the way to make it look inset (and consistent with the other note styles) with a dark face would be to change the shadow to instead be a 1 pixel downwards transparent white one (e.g. 0 1px 0 rgba(255,255,255,.25)).

@cobyism Agreed, your version looks very nice too. Either way is fine. 👍

[parkr]

Alright! I went with the darker color because I preferred it so thanks for the tip about the shadow, @cobyism!

@troyswanson Added some verbiage around installing pre-releases to the installation page.

@benbalter @mattr- I made the "where this is available" text a bit less clear-cut as requested. Also talked about building from master in installation docs.

[troyswanson]

😍 Looks great!

[parkr]

@troyswanson Would you mind running through each of them quickly and making sure I'm sane?

[troyswanson]

Aye, it all looks good, although in fairness, the new "development version" section of the Installation page is pretty greek to me. 👍

[troyswanson]

🎉 Yay, a step forward for the docs!