Plan for registering/submitting hacks

benfoxall commented 7 years ago

Background: We're going to have constraints on time, so having a simple central place for all hacks should make it easier to keep track on signups and to go through hacks at the end of the day.

Plan

Each user/team would submit their hack by adding a file to this repo in an 'entries/' directory. Files would be named by github username - /entries/${github_username}.txt.

As an example - I might create the file/entries/benfoxall.txt with the following content:

---
name: Bens awesome hack
leader: Bobs SMS team
url: https://benjaminbenben.com/my-hack.html
---

When you send a sms to 0754321234 the background of this page will change colour

All entries would be PRs to the main repo - by having separate files named by github, this should make it much easier to merge and for allowing updates/tweaks.

All attendees would be listed on the main page with jekyll. And we'd also be able to have a page /present.html which lists the name/urls of each hack for when we get down to presentations at the end of the hack.

Secret urls (extra)

Some people might want to keep their url secret until the final presentation, in this case we could allow people to encode their url (I think I've found a pretty nice way of implementing this). In that case, the submission would look something like this:

----
name: Secret hack
secret_url: ED1KCHSWwxdNhJ0IQN+vhmAgPSe+UfQSv8eQLaSwulBqZu3gI2TMb/xOefcd0YBtKZOYHphkWoqJjOaQZ6rnd6mABlWFS1BPjKM9MU6vkfqk2i7Htsi3VjTr+16YxBnxpEeQy6hRiA1+WSK2xP/Tw2PAeAOx2/sryyhRNKFHZAk=
---

This is a secret hack

Things we need to do:

is this a good way of doing submissions - could it be easier
create a page to display these instructions to attendees
add list of users to main page
create /present.html page

@AverageMarcus @omgmog @spikeheap - would love to know your opinions on this

AverageMarcus commented 7 years ago

What if people work in teams?

omgmog commented 7 years ago

Collections are perfect for this. We could use .json to represent each entry though, to have a more universal data structure for entries (would be cool to be able to use the data from elsewhere directly without having to run through Jekyll or something...)

So the structure:

entries/{team or user slugified}.json

{
  "name": "Fancy name for the team or user",
  "members": [
  // Only need members if it's a team...
      {
        "github": "omgmog",
        "name": "Max Glenister"
      }
    ],
  "hacks": [
    {
      "title": "Title of a hack",
      "description": "This hack is something magical that I'm working on",
      "url": ""
    },
  // A team or user can have multiple hacks!
  ]
}

I'm all for submission by PR -- it has worked in the past (Sushack) and if we provide an empty/example file to get people started it should be super simple.

We can have the entries[i].hacks[j].url as a completely optional thing until people are ready to make their hack public.

benfoxall commented 7 years ago

Ace - thanks for the feedback.

Good shout about the teams. I was thinking that there'd be one person submitting for the team, though I guess it's be good to be able to list other members of the team.

With using .json files, does that mean that we can do away with front matter ---'s? I guess that might be great for people who haven't used jekyll before.

(would be cool to be able to use the data from elsewhere directly without having to run through Jekyll or something...)

Originally I was looking into having a tiny form that you can log in with github and it automatically creates/updates username.txt or an external db - though I came to the conclusion that it would take extra effort to build, and might go wrong. We'd also lose the free control & auth that comes from using PRs.

// A team or user can have multiple hacks!

Perhaps in this case they could make their url a list of links to the other hacks they've made? I think that makes the schema a bit simpler. I think we want to have this as minimal as possible and try and make it as easy as possible for people to get involved.

omgmog commented 7 years ago

So simplified structure:

// data/omgmog.json
[{
  "name": "Max's Awesome Team",
  "members": [
      {
        "github": "omgmog",
        "name": "Max Glenister"
      }
    ],
  "hacks": [
    "http://status.omgmog.net/",
    "https://blog.omgmog.net/line-finder/"
  ]
}]

Whipped up an example:

https://github.com/omgmog/jekyll-json-test https://blog.omgmog.net/jekyll-json-test/?

Caveats:

order is alphabetical based on filename

benfoxall commented 7 years ago

Okay; Cool!

Do you think we should nest this under /_data/entries/omgmog.json? I guess that means we could put guides/organisers/helpers in other directories if so (and maybe have a repeat event later in the year).

I still think we should stick to single entries; we're going to be under a tonne of pressure with the final presentations, by having a single url per team, it means we can load it up and get them to come up and show it. As I said before - if there are multiple things that they've put together, then the url could be used as an index.

Out of interest - why json over yaml?

AverageMarcus commented 7 years ago

More people are familiar with JSON than with yaml.

AverageMarcus commented 7 years ago

What if a hack isn't a website? (Thinking chatbots)

omgmog commented 7 years ago

Perhaps we can just take a description, and handle that as markdown on the Jekyll side of things

benfoxall commented 7 years ago

The "submit a url per hack" is to streamline the presenting of hacks. If you think about JSOxford Show+Tell - the reason we get people to provide urls is because there's always issues with switching between machines; by loading up on a single machine you avoid that. On Thursday - we're going to need to be even more streamlined.

There's also another really nice thing that it'll create a list of all the hacks so you can look through them later to see what people did.

What if a hack isn't a website? (Thinking chatbots)

In this case - I guess a screenshot or video url would be an option, or a hangout url to a screenshare from your laptop if you really want to do a live demo.

I think it could work for non-online hacks too. Say if you've built a board game - you can take a photo, get a public url from G+, submit that.

I've started a document with a running plan of the event and I've added describing this in the intro.

Perhaps we can just take a description, and handle that as markdown on the Jekyll side of things

Is this for a non-web hack? I guess that description could be submitted as a gist? If we're going down the markdown route - perhaps it'd be better to go back down the collections route?

Right, we need to decide this. The way I see it - we've got two options:

collections - /_entries/benfoxall.yml

---
name: Ben's awesome hack
url: http://example.com/foo
guide: lisa
---
This is a virtual cardboard box for google cardboard.

I was working with [Jane](http://twitter.com/jane) & Frank

data - /_data/benfoxall.json

[{
  "name": "Ben's awesome hack",
  "members": [
      {
        "github": "benfoxall",
        "name": "Ben Foxall"
      }
    ],
  "url": "http://example.com/foo",
  "description": "This is a virtual cardboard box for google cardboard"
}]

I'm personally in favour of the collections still - I think that it's better to have a minimal approach (both for people signing up, and building the actual jekyll site). I know more people are familiar with json, but if we keep things super simple and let people to put any extra information into the markdown body - then I think it could make things a bit easier.

Though I'm also happy to go down the _data/json route - @omgmog I know that you've got this working in your version - and you're way more up on Jekyll than I am - so if you think it's a better approach, then we can do that.

So, Decisions:

we stick to url submissions & add stuff in the hack intro to tell people how to submit non-web things
omgmog - decide on collection vs data and we'll go with that.

(sorry this is so long, I'm in a massive rush)

omgmog commented 7 years ago

Okay there is something at http://jsoxford.com/hack/entry now to make this a bit easier.

Exact details of it might change as/when @ben gets an internet connection. :100:

AverageMarcus commented 7 years ago

@omgmog The guide dropdown needs to have a "No Guide" option

omgmog commented 7 years ago

@AverageMarcus done. https://github.com/jsoxford/hack/blob/master/_data/guides.yml

Also feel free to add yours

AverageMarcus commented 7 years ago

Awesome. Will do. I've just fixed the "New File" link.

benfoxall commented 7 years ago

Right, I think we've got this fairly down now.

I guess we've split up registration (creating your hack file) & submitting (adding a url).

We should probably rename /entry to /register, and make a new route called /submit which gives instructions for updating your hack.

When shall we aim to open registrations? Tomorrow? or Tonight? I guess when we do, we'd add a big pink button that links to register. We could add the submit button tomorrow night.

[x] decide when to open registrations (tonight!)
[x] change /entry to /register
[ ] create a /submit page
[ ] stub out 'register' button on homepage
[ ] rename /entries to /hacks
[ ] update /hacks to look cooler?

AverageMarcus commented 7 years ago

I think open registrations tonight. A lot of people are getting into town and getting excited. Would be good to be able to get an early indicator of numbers too.

omgmog commented 7 years ago

Tonight and also promote it at the quiz?

jsoxford / hack

Plan for registering/submitting hacks #3

Plan

Secret urls (extra)