events.json or events/<name>.json?

martinheidegger commented 8 years ago

Subtask for #6

Right now I implemented a events.json as single file because:

Easy to process
Easy to modify

But there is the possibility of having events/<name>.json instead. This would allow:

Theoretically infinite events
No merge-conflicts when adding events

but it also comes with the slight downside that the name needs to be duplicated because events/<name>.json needs to follow file-name-restrictions (no space etc.)

To me the current situation is perfectly fine and i feel the other version is over-engineered. but I would like to see some +1's

Note: This issue exists also for documentation purposes

SomeoneWeird commented 8 years ago

I'd +1 for events/<name>.json

martinheidegger commented 8 years ago

@SomeoneWeird Do you mind to expand the argument :)

martinheidegger commented 8 years ago

Note: I just found another reason against events/<name>.json: With events.json it is very easy for the chapter maintainers to show the events on their homepage (simple ajax request). With events/<name.json> They either need to maintain an index somewhere or use the github api to list the folder.

bnb commented 8 years ago

@martinheidegger How would events.json prevent theoretically infinite events?

If we have events/<name>.json, there would need to be a naming convention in place to prevent filename collisions. This could be as simple as adding a date to the slug, such as events/empire-state-building-2015-06-19.json, where 2015-06-19 is YYYY-MM-DD (there's good reasoning for this order, I can link to a discussion on nodejs/evangelism about it later if requested).

Conversely, if we have events.json, events could have the same name given there is some sort of unique identifier inside an event object (that's my term, can't look at the source right now to see what the object name is for an event).

I think the simplest identifier would be order of event - event 1 would have a property, along the lines of id or order, of 1. Event 2 would have that property's value be 2. One issue with this is if you get to event 22, listing the numbers in order would result in 1, 11, 12, 13, 14, 15, 16, 17, 18, 19, 2, 20, 21, 22 instead of from smallest to largest.

So, having a three or four digit prefix placeholder would work: 'id': '001'. If we think there will be over 1k events at any NodeSchool group, then we should go with a four digit prefix over a three digit one so we don't have to change the spec later.

So, my vote is for events.json.

martinheidegger commented 8 years ago

As the events.json file grows larger the amount of json to download will grow larger too with it the response time of any tool that loads this events.json until it becomes unusable at some point (in the very far future). If every event is in his own file you can have - with naming conventions - that allows to have a very large amount of events.

I do not see the need for an order. The date/time will serve just fine for sorting. The name should be unique but the current implementation already is that that (and people can name the events freely).

fforres commented 8 years ago

We've had that very same problem when trying to download or maintain a big JSON file for a no-backend app, so I vouch for the events/<name><date>.json.

Would it be too weird to have an events.json file to serve as index for the events/<name><date>.json file?

PS: @bnb would love to see that discussion to the link.

martinheidegger commented 8 years ago

If we were to go with one json file per event then I currently think that it should be like this:

Having a in the path would restrict the characters we have to add. In order to name it like we want the name should go in the event.json (on the topic of: no duplicate information).
... thus the path could be like events/<date>T<time>.json because then the ordering in the folder would match the natural order of the events.
Since the start-time is given in the path we can drop the startTime/ startDate/endTime/endDate properties and instead use a duration(http://momentjs.com/docs/#/durations/creating/) field.
The lookup of events should then happen in nodeschool-admin events using github Data. It should not be forbidden to create a events.json with an index but also not be required..

Regarding the discussion on the time format: http://xkcd.com/1179/

bnb commented 8 years ago

@fforres Not quite as involved a discussion as I remember, but here it is: https://github.com/nodejs/evangelism/issues/18

bnb commented 8 years ago

@martinheidegger Could you describe what you mean when you say:

The lookup of events should then happen in nodeschool-admin events using github Data.

What is the process/structure of using GitHub data?

SomeoneWeird commented 8 years ago

+1 for events/<name><YYYY-MM-DD>.json

martinheidegger commented 8 years ago

@SomeoneWeird Do you mind to expand the argument :)

I am in favor of events/<YYYY-MM-DD>T<HH-MM>.json (maybe better without the time?). I can accept events/<YYYY-MM-DD>(T<HH-MM>)_<name>.json since it will have the readable urls (even though there will be duplicate data). But I do not know why you would put the name in front of the date?!

martinheidegger commented 8 years ago

@bnb

The lookup of events should then happen in nodeschool-admin events using github Data.

Let me rephrase: nodeshool-admin events should be a new command of nodeschool-admin that should list the events of one chapter using the github API.

bnb commented 8 years ago

@martinheidegger Okay, I'm a huge :+1: on that - it's really awesome.

martinheidegger commented 8 years ago

Extracted the events method into own issue: #37.

I will accept a PR that changes the event creation & linting to have each event in an own file.

In lieu of better arguments I am for the name pattern events/<YYYY-MM-DD>T<HH-MM>(_<name>).json in order for the events to be sorted in the folder, date first.

Since a time is required for events (even when they start at 00:00) and to enforce consistency the time MUST to be noted in the file name. Since startTime and startDate are noted in the path, the current startDate and startTime fields MUST NOT be present in the .json files. The name in the path is a urlsafe_name and as such different from the name within the .json files. The urlsafe_name CAN be in the file path and MUST be generated automatically if not provided in the path from the name and be contained in the #37 output.

If someone has the time to work on this it would be awesome :smile:

martinheidegger commented 8 years ago

https://twitter.com/leichtgewicht/status/710348006185259008

martinheidegger commented 8 years ago

I extracted the specification of one event into a own module and I am working on the event listings http://github.com/opengh/open-event

dinodsaurus commented 8 years ago

Awesome, I started implementing your lib for all the events in nodeschool-admin

nodeschool / admin

events.json or events/<name>.json? #7