Document naming conventions and repo structure

[jfly]

See discussion on #106 (comment).

We're starting to form some opinions about naming conventions (kebab case, longer, more readable ids). @dmint789 also pointed out that it's really unclear what the "ids" of our icons actually are. For example, we have:

• event-333: corresponds to WCA event id 333 (documented in the WCIF here, which links to this sql file, which I guess is the ultimate source of truth for WCA event ids)
• unofficial-333-mirror-blocks: we're the source of truth for these things! But it's unclear if the id people should use in their databases is 333-mirror-blocks or unofficial-333-mirror-blocks.
  • We don't currently enforce uniqueness of names in this repo (in other words, we could create a jfly.svg in both the events and the unofficial directories). We haven't thought about if we'd rather enforce uniqueness across "categories".

[mintydev789]

Also, we should try to be consistent when it comes to naming events that are extensions of existing events. E.g. 3x3 Blindfolded 2 Person Relay should be 333bf-2-person-relay, since it is simply an extension of the event 3x3 Blindfolded, which has the id 333bf.

[lgarron]

Bringing over the discussion from other issues:

I think we should go with underscores for event names. The only legacy compat concern would be mirror blocks, which is unlikely to be used by a significant number of pages yet.

[mintydev789]

Why do you want underscores over dashes? The way I see it, it makes no difference

[lgarron]

Why do you want underscores over dashes? The way I see it, it makes no difference

Underscores tend to be better for identifiers, since:

• They can be used in variable and field names in many more common languages than hyphens.
• Most browsers and operating systems will consider different sets of letter as the same word when connected by underscores (e.g. when double-clicking to select).

For our CSS class names, it would also help isolate the event ID from the icon type prefix.

[mintydev789]

Oh, I see. Well, I don't have a strong opinion on this as long as we keep things consistent and don't mix naming conventions.

[mintydev789]

@jfly Thoughts?

[jfly]

I'm fine with underscores. Let's leave this issue open to track a little more work:

• let's actually enforce a regex for event ids
• let's add a blurb somewhere explaining the events vs unofficial folders and how stable we promise the ids to be

[lgarron]

• let's actually enforce a regex for event ids

Sounds like a good idea!

• let's add a blurb somewhere explaining the events vs unofficial folders and how stable we promise the ids to be

I propose:

• Select a reasonable name at icon creation time.
• Once an event is assigned an official ID by the WCA, that's permanent (even if the event is removed). We're happy if this adopts the unofficial ID we used, but if not — we're also glad to have been the testing ground.
• We'll try to keep renames/removals of unofficial events to a minimum, but no guarantees except:
  • Any removed/renamed unofficial event will remain as an alias for X time (1 year?).

It might be worth keeping track of some of this in code — #112 can generate TypeScript code to refer to icons, and I also want to include a bit of event metadata in the repo (so you can semantically e.g. go from a speed event to its associated BLD event or team event or vice-versa, etc.).

[mintydev789]

I feel like we should keep things permanent in general, not just for wca events. This should be the last time we make an icon id change in my opinion, because it's not a good strategy to change something as important as the id of an event, even if it's unofficial.

And what's this point about removals? Why would we ever remove an icon?

[lgarron]

I feel like we should keep things permanent in general, not just for wca events. This should be the last time we make an icon id change in my opinion, because it's not a good strategy to change something as important as the id of an event, even if it's unofficial.

I think this is reasonable in principle, but we're almost certainly going to run into edge cases over time. I'm not arguing that we should ever do it lightly, just that we set a baseline for the requirements in case it ever happens.

And what's this point about removals? Why would we ever remove an icon?

The main one I have in mind is removing something from unofficial if it ever becomes official. I still don't know if that's a good idea, but again just setting a baseline.