search

exercism / legacy-docs

Other
84 stars 55 forks source link

exercises.md: add instruction for uuid length #110

Closed FridaTveit closed 6 years ago

FridaTveit commented 6 years ago

On the Java track we've had quite a few people submit new exercises with uuids that are too long. I thought it might be nice to document the structure of the uuid for people who don't use configlet or use an old version of configlet :)

rpottsoh commented 6 years ago

Should the document suggest an alternate source for generating the UUID (for those who do not have or are unaware of configlet)? https://www.uuidgenerator.net/ creates a version 4 ID by default, which seems to be the type of UUID the latest version of configlet is producing.

cmccandless commented 6 years ago

@FridaTveit

people who don't use configlet

I would argue that configlet is a standard tool for Exercism track development. Anywhere else, if you contribute to a project, there will be a standard toolset that you will have to use.

rpottsoh commented 6 years ago

or use an old version of configlet

Not to get too far off topic, but it might be nice if configlet could detect if it is the latest version or not. Furthermore if it had the ability to upgrade itself as the CLI is capable of.

The preferred method of generating UUIDs would be via. the configlet.

For now it might be best just to add a blurb to make sure the version of the configlet agrees with the https://github.com/exercism/configlet/releases/latest.

coriolinus commented 6 years ago

I would argue that configlet is a standard tool for Exercism track development. Anywhere else, if you contribute to a project, there will be a standard toolset that you will have to use.

Sure, but

  1. configlet hasn't always produced valid uuids
  2. Configlet doesn't do all the work of producing a valid config.json entry anyway
  3. Whether or not configlet is standard isn't the question here.

We can't depend on updates to configlet lint catching this, because the long uuids are a product of depreciated versions of configlet in the first place. Adding documentation is a good start, but I'd also assert that a better policy would be to add CI checks which verify that all UUIDs are valid.

It shouldn't matter where a UUID comes from; configlet is a convenient source, but it's far from the only one. Personally, I tend to do python3 -c "import uuid; print(uuid.uuid4())", because it still comes to mind sooner than configlet uuid for that task.

kytrinyx commented 6 years ago

Not to get too far off topic, but it might be nice if configlet could detect if it is the latest version or not.

I've opened https://github.com/exercism/configlet/issues/113 to address this.

Furthermore if it had the ability to upgrade itself as the CLI is capable of.

I've opened https://github.com/exercism/configlet/issues/112 to address this.

For now it might be best just to add a blurb to make sure the version of the configlet agrees with the https://github.com/exercism/configlet/releases/latest.

That sounds like a good first step to me.

Adding documentation is a good start, but I'd also assert that a better policy would be to add CI checks which verify that all UUIDs are valid.

Agreed. There's an open issue here: https://github.com/exercism/configlet/issues/99

FridaTveit commented 6 years ago

Those sound like great improvements, thanks @kytrinyx :)

However, I still think adding this small bit of documentation could be useful, especially until those improvements have been implemented. Even after that I think it might be nice for the person adding the new exercise to easily be able to tell if their new uuid is in the correct format.

But if you don't think it would be useful here then I'd be happy to move it to the java track's documentation :)

FridaTveit commented 6 years ago

@kytrinyx, @rpottsoh, @coriolinus, @cmccandless thanks for your comments! :) Any decision on whether or not you think this documentation would be useful?

rpottsoh commented 6 years ago

@kytrinyx and I said:

For now it might be best just to add a blurb to make sure the version of the configlet agrees with the > >https://github.com/exercism/configlet/releases/latest.

That sounds like a good first step to me.

Along with what you have added I think a reminder to make sure configlet is current would be beneficial to this document.

FridaTveit commented 6 years ago

@rpottsoh sure I can add that as well :)