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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added changelist to site as history #1065

Merged
merged 19 commits into from Jun 2, 2013

Conversation

Projects
None yet
6 participants
@zachgersh
Contributor

zachgersh commented May 9, 2013

Hey Guys,

I whipped this up for the request of a set of releases / release notes for jekyll. Added a rake task to basically copy over the changelist directly into the site documentation and remove the old changelist that is there.

Here is what I believe I have left to do:

  • automagically add the formatting to the top of the changelist.md

If this is completely the wrong path let me know and I can either change this entirely or refactor it.

@parkr

This comment has been minimized.

Member

parkr commented May 9, 2013

Let's call it "Changelog" or "History", but otherwise I like it.

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 9, 2013

Sure, I can change that tonight! I don't know if @cobyism wants to slightly tweak the layout of this page. Hopefully he will give it a look as well.

On May 9, 2013, at 2:44 AM, Parker Moore notifications@github.com wrote:

Let's call it "Changelog" or "History", but otherwise I like it.


Reply to this email directly or view it on GitHub.

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 9, 2013

Could also use some sort of RSS button maybe? Another thing possibly for @cobyism!

@cobyism

This comment has been minimized.

Member

cobyism commented May 10, 2013

@zachgersh It would be good to have some styles for this format to make it a bit easier to parse/scan. I think it’s mainly the way the stock-standard headings look in proximity to each other that makes this feel a naked:

screen shot 2013-05-10 at 9 12 00 am

I think what I’d aim for here is a bit more visual distinction between a few sets of elements:

  • the version number and the date.
  • the version/date information, and the groups of bullets.
  • each version/release should be clearly separate from the one before/after it.

I’m not sure what the best visual way is to do this visually, and I’m at a conference this week, so let me have a think and see if I can come up with something that’ll work 😀

@parkr

This comment has been minimized.

Member

parkr commented May 10, 2013

Can we auto-highlight those GitHub Issue links?

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 10, 2013

@cobyism have a 🍺 at the drinkup for me. You nailed exactly what should be highlighted on the page. I still have some changes to make so you have time on the design.

@parkr do you want to just highlight them stylistically or go through and point them back to github programmatically? I could also parse the issues via regex.

@parkr

This comment has been minimized.

Member

parkr commented May 10, 2013

I suppose I should start linking them in the history, I just don't want to have to go back and do it for everything :)

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 10, 2013

I can regex it pretty easily. We can even run it on the history before copying it over.

@parkr

This comment has been minimized.

Member

parkr commented May 10, 2013

Wishlist:

  • GFM parses #\d+ into links (@cobyism @benbalter)
  • We have some sort of rakefile script which takes the latest release's stuff and creates a post from it.
@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 10, 2013

The rake bit I will take care of without a doubt.

GFM already does:

https://help.github.com/articles/github-flavored-markdown#issue-autocompletion

Issue autocompletion

Typing # will bring up a list of Issue and Pull Request suggestions. Type a number or any text to filter the list, then hit tab or enter to complete the highlighted result.

@parkr

This comment has been minimized.

Member

parkr commented May 10, 2013

But not in the Readme's, so I guess that's something else altogether.

@benbalter

This comment has been minimized.

Contributor

benbalter commented May 10, 2013

There's two flavors of md on GitHub. Issues and comments use GFM (which has autocomplete), readmes are standard markdown. See http://developer.github.com/v3/markdown/ for more details.

@parkr

View changes

site/_posts/2013-05-08-changelist.md Outdated
---
layout: docs
title: Changelist
prev_section: upgrading

This comment has been minimized.

@parkr

parkr May 10, 2013

Member

You'll need to add a permalink: /docs/history/ here.

@parkr

View changes

Rakefile Outdated
# First lets go ahead and format the file correctly (mainly bullet points)
if File.exist?("History.markdown")
file_time = File.read("History.markdown")
replaced = file_time.gsub(/\s{2}\*{1}/, "-")

This comment has been minimized.

@parkr

parkr May 10, 2013

Member

If you could sub the #'s here so they're links to https://github.com/mojombo/jekyll/issue/NUM, that'd be splendid.

replaced = replaced.gsub(/#(\d+)/, "https://github.com/mojombo/jekyll/issue/$1")

Or something

This comment has been minimized.

@zachgersh

zachgersh May 10, 2013

Contributor

Definitely.

On May 10, 2013, at 1:29 PM, Parker Moore notifications@github.com wrote:

In Rakefile:

@@ -143,6 +147,22 @@ namespace :site do
end
puts 'Done.'
end
+

  • desc "Move the changelist over to _posts directory and update its formatting."
  • task :changelist do
  • First lets go ahead and format the file correctly (mainly bullet points)

  • if File.exist?("History.markdown")
  •  file_time = File.read("History.markdown")
    
  •  replaced = file_time.gsub(/\s{2}*{1}/, "-")
    
    If you could sub the #'s here so they're links to https://github.com/mojombo/jekyll/issue/NUM, that'd be splendid.


Reply to this email directly or view it on GitHub.

This comment has been minimized.

@parkr

parkr May 10, 2013

Member

And

replaced = replaced.gsub(/##\s(\d\.\d+\.\d+)/, "https://github.com/mojombo/jekyll/tree/v$1")
@parkr

View changes

Rakefile Outdated
# Now we need to copy the file into the _posts directory with the proper date
Dir.chdir('site/_posts') do
sh "rm -rf *-changelist.md"
File.open("#{file_date}-changelist.md", "w") {|file| file.write(replaced)}

This comment has been minimized.

@parkr

parkr May 10, 2013

Member

This all will have to change:

front_matter = {
  "title" => "Jekyll History",
  "layout" => "default",
  "permalink" => "/docs/history/",
  # ...
}
Dir.chdir("site/docs") do
  File.open("history.md", "w") do |f|
    f.write("#{front_matter.to_yaml}\n\n")
    f.write(replaced)
  end
end

This comment has been minimized.

@zachgersh

zachgersh May 10, 2013

Contributor

Yeah. Will also add logic to make sure I don't rewrite a change list that was already written.

On May 10, 2013, at 1:31 PM, Parker Moore notifications@github.com wrote:

In Rakefile:

@@ -143,6 +147,22 @@ namespace :site do
end
puts 'Done.'
end
+

  • desc "Move the changelist over to _posts directory and update its formatting."
  • task :changelist do
  • First lets go ahead and format the file correctly (mainly bullet points)

  • if File.exist?("History.markdown")
  •  file_time = File.read("History.markdown")
    
  •  replaced = file_time.gsub(/\s{2}*{1}/, "-")
    
  • Now we need to copy the file into the _posts directory with the proper date

  •  Dir.chdir('site/_posts') do
    
  •    sh "rm -rf *-changelist.md"
    
  •    File.open("#{file_date}-changelist.md", "w") {|file| file.write(replaced)}
    
    This all will have to change:

Dir.chdir("site/docs") do
File.open("history.md", "w") do |f|
f.write(replaced)
end
end

Reply to this email directly or view it on GitHub.

This comment has been minimized.

@parkr

parkr May 10, 2013

Member

How come? Everything is in the History file in the root, this is just a Jekyll-enhanced version.

This comment has been minimized.

@zachgersh

zachgersh May 10, 2013

Contributor

I was actually referring to the posts that are generated from the history doc (via the rake task you mentioned). I get what you are saying, you want a full history + a post generated each time a new version is added to the history.

This comment has been minimized.

@parkr

parkr May 10, 2013

Member

Haha, yes. Sorry for the confusion, my b.

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 12, 2013

So, the generation fo the XML file to support the RSS feed on just the history page (remember posts about release have a separate and easier xml to generate) is taking me longer than expected.

Unfortunately, unless someone has an easy way to do it, I have to go back and parse the whole index.html using nokogiri to contruct the XML based on the info contained.

I think I have a bead on how to finish but I wanted to update everyone on progress.

@@ -152,6 +152,7 @@ Gem::Specification.new do |s|
site/docs/upgrading.md
site/docs/usage.md
site/docs/variables.md
site/docs/history/index.md

This comment has been minimized.

@parkr

parkr May 12, 2013

Member

We're using a different format so everything is in the docs folder as files, then setting the permalink. Can you change this file to be site/docs/history.md?

This comment has been minimized.

@zachgersh

zachgersh May 12, 2013

Contributor

Did this so we could jam the rss feed for history under the /docs/history folder to keep everything self contained. Wanted to make sure the RSS for the news section you are creating could live at the root of the site.

This comment has been minimized.

@parkr

parkr May 12, 2013

Member

so you'd have like site/docs/v1.0.0.md?

This comment has been minimized.

@zachgersh

zachgersh May 12, 2013

Contributor

That's where your release rss will probably live. The history RSS (which we said you could follow separately) will live under /docs/history/rss.xml when parsed.

This comment has been minimized.

@parkr

parkr May 12, 2013

Member

but when rendered it'll be /releases.atom or something?

This comment has been minimized.

@zachgersh

zachgersh May 12, 2013

Contributor

yes. There will be two.

Yours for the news section will be releases.atom

Mine for the history section will be something like history.atom

Makes sense?

This comment has been minimized.

@parkr

parkr May 12, 2013

Member

based on our discussion, let's move this to site/docs/history.md

This comment has been minimized.

@mattr-

mattr- May 12, 2013

Member

👍 for site/docs/history.md

@parkr

View changes

Rakefile Outdated
# Replacing the contents of the file for the markdown bullets & issue links
rep_bullets = file_time.gsub(/\s{2}\*{1}/, "-")
rep_links = rep_bullets.gsub(/#(\d+)/) do |word|
"[#{word}](https://github.com/mojombo/jekyll/issue/#{word.delete("#")})"

This comment has been minimized.

@parkr

parkr May 12, 2013

Member

The word will just be the number, not the leading hash, based on the regexp above.

This comment has been minimized.

@zachgersh

zachgersh May 12, 2013

Contributor

This is what it looks like currently, what is the problem?

screen shot 2013-05-12 at 8 00 43 am

This comment has been minimized.

@parkr

parkr May 12, 2013

Member

the # shouldn't be highlighted if that regex is correct. unless word is the whole match, not just the group

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 12, 2013

@mattr- for review as well.

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 12, 2013

Adjusting the title of this based on discussions with @parkr.

@mattr-

View changes

Rakefile Outdated
desc "Move the History.markdown over to the /docs/history directory."
task :history do
# First lets go ahead and format the file correctly (mainly bullet points)
puts "Generating the History doc!"

This comment has been minimized.

@mattr-

mattr- May 12, 2013

Member

I don't like this exclamation point here. We're just making a statement. Better to have just a normal period here, IMHO

@mattr-

View changes

Rakefile Outdated
if File.exist?("History.markdown")
file_time = File.read("History.markdown")
# Replacing the contents of the file for the markdown bullets & issue links
rep_bullets = file_time.gsub(/\s{2}\*{1}/, "-")

This comment has been minimized.

@mattr-

mattr- May 12, 2013

Member

this could use a method

This comment has been minimized.

@zachgersh

zachgersh May 12, 2013

Contributor

Do you want the method to encapsulate just the file open or the file_open + the gsubs?

This comment has been minimized.

@mattr-

mattr- May 13, 2013

Member

A comment probably seems best. I don't think it particularly matters where
it goes as long as people know about it. 😃

On Sun, May 12, 2013 at 4:15 PM, Zach notifications@github.com wrote:

In Rakefile:

@@ -143,6 +147,33 @@ namespace :site do
end
puts 'Done.'
end
+

  • desc "Move the History.markdown over to the /docs/history directory."
  • task :history do
  • First lets go ahead and format the file correctly (mainly bullet points)

  • puts "Generating the History doc!"
  • if File.exist?("History.markdown")
  •  file_time = File.read("History.markdown")
    
  •  # Replacing the contents of the file for the markdown bullets & issue links
    
  •  rep_bullets = file_time.gsub(/\s{2}*{1}/, "-")
    

Do you want the method to encapsulate just the file open or the file_open

  • the gsubs?


Reply to this email directly or view it on GitHubhttps://github.com//pull/1065/files#r4186499
.

@mattr-

This comment has been minimized.

Member

mattr- commented May 12, 2013

I think we need something at the top of history.md so that people don't attempt to edit it. Something like

WARNING! This file is automatically generated. Any changes you make to this file will be overwritten

or so.

Are we planning on replacing history.markdown at the root of the repo with the file under site?

@parkr

This comment has been minimized.

Member

parkr commented May 12, 2013

@mattr- Nah, this would just be a copy of the history all linkified for easy web perusal.

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 12, 2013

@mattr- can I just put that in the front matter or would you prefer it as a paragraph / comment??

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 22, 2013

Can we add this to 1.0.3?

I'd like to wrap this :)

@zachgersh

This comment has been minimized.

Contributor

zachgersh commented May 29, 2013

hey @parkr @mattr- been super busy but I wanted to polish this off!

Hope this is better and ready to merge.

@@ -110,7 +114,7 @@ namespace :site do
end
desc "Commit the local site to the gh-pages branch and publish to GitHub Pages"
task :publish do
task :publish => [:history] do

This comment has been minimized.

@parkr

parkr May 29, 2013

Member

If we run this every time we publish the site, won't we have HEAD? Should this page be for more than just the versions?

This comment has been minimized.

@zachgersh

zachgersh May 29, 2013

Contributor

Yeah, you will have Head. I don't see any issue with Head being in the changelist but we can exclude it as needed.

What would you propose having on the page with the versions? I think your blog post section is going to handle everything beyond versions.

@parkr

This comment has been minimized.

Member

parkr commented May 29, 2013

LGTM - @mattr-?

@mattr-

This comment has been minimized.

Member

mattr- commented Jun 2, 2013

I think the gemspec is still missing the update to use site/docs/history.md. Once that's been updated, I think this can be merged.

@parkr

This comment has been minimized.

Member

parkr commented Jun 2, 2013

The gemspec is automatically overwritten when we run rake gemspec. I wouldn't worry about it. :)

parkr added a commit that referenced this pull request Jun 2, 2013

Merge pull request #1065 from zachgersh/changelist_page
Added changelist to site as /docs/history/

@parkr parkr merged commit 27cf7aa into jekyll:master Jun 2, 2013

1 check passed

default The Travis CI build passed
Details

parkr added a commit that referenced this pull request Jun 2, 2013

@parkr

This comment has been minimized.

Member

parkr commented Jun 2, 2013

Thanks @zachgersh 🌞

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