New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Unreleased features warnings on site #2061

Merged
merged 9 commits into from Feb 20, 2014

Conversation

Projects
None yet
7 participants
@parkr
Member

parkr commented Feb 17, 2014

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

screen shot 2014-02-17 at 3 51 43 pm

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

@parkr parkr added this to the 2.0 milestone Feb 17, 2014

@parkr parkr added the Documentation label Feb 17, 2014

@parkr parkr removed this from the 2.0 milestone Feb 17, 2014

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 17, 2014

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

This comment has been minimized.

Member

parkr commented Feb 17, 2014

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

unreleased

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 17, 2014

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

This comment has been minimized.

Member

parkr commented Feb 17, 2014

Fair enough! Pushed :)

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 17, 2014

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

@parkr

This comment has been minimized.

Member

parkr commented Feb 17, 2014

@troyswanson Probably! Just need @mattr-'s 馃憖 and would love @benbalter's :brain:

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 17, 2014

Probably!

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

@parkr

This comment has been minimized.

Member

parkr commented Feb 17, 2014

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

This comment has been minimized.

Member

troyswanson commented Feb 17, 2014

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

This comment has been minimized.

Contributor

benbalter commented Feb 17, 2014

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

This comment has been minimized.

Member

parkr commented Feb 17, 2014

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-

This comment has been minimized.

Member

mattr- commented Feb 18, 2014

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. 馃槂

@mattr- mattr- assigned parkr and unassigned mattr- Feb 18, 2014

@cobyism

This comment has been minimized.

Member

cobyism commented Feb 18, 2014

@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鈥檚 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:

2014-02-18 at 10 11 am

@@ -24,7 +24,7 @@ behind [GitHub Pages](http://pages.github.com), which means you can use Jekyll
to host your project鈥檚 page, blog, or website from GitHub鈥檚 servers **for
free**.
## ProTips鈩, Notes, and Warnings
## ProTips鈩, Notes, Warnings, and Unreleased Features

This comment has been minimized.

@cobyism

cobyism Feb 18, 2014

Member

I鈥檓 wondering if it wouldn鈥檛 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鈥檛 have to be updated.

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

2014-02-18 at 10 19 am

This comment has been minimized.

@troyswanson

troyswanson Feb 18, 2014

Member

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

This comment has been minimized.

@parkr

parkr Feb 19, 2014

Member

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"!

This comment has been minimized.

@mattr-

mattr- Feb 19, 2014

Member

orphaned words kill my inner typography nerd

poor nerd. :finnadie:

馃憤 to "Helpful Hints"

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 18, 2014

It鈥檚 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

This comment has been minimized.

Member

parkr commented Feb 20, 2014

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.

@mattr- mattr- assigned mattr- and unassigned parkr Feb 20, 2014

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 20, 2014

馃槏 Looks great!

@parkr

This comment has been minimized.

Member

parkr commented Feb 20, 2014

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

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 20, 2014

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

mattr- added a commit that referenced this pull request Feb 20, 2014

Merge pull request #2061 from jekyll/unreleased-features-warnings-on-鈥
鈥ite

Unreleased features warnings on site

@mattr- mattr- merged commit 55059a6 into master Feb 20, 2014

1 check passed

default The Travis CI build passed
Details

@mattr- mattr- deleted the unreleased-features-warnings-on-site branch Feb 20, 2014

mattr- added a commit that referenced this pull request Feb 20, 2014

@troyswanson

This comment has been minimized.

Member

troyswanson commented Feb 20, 2014

馃帀 Yay, a step forward for the docs!

@zdroid

This comment has been minimized.

Member

zdroid commented on site/docs/assets.md in 768a47d Feb 21, 2014

What about indent here?

@jekyll jekyll locked and limited conversation to collaborators Feb 27, 2017

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.