Arc Forum | Labeling hacks

Arc Forum

2 points by CatDancer 5672 days ago | 6 comments

OK, a lot of discussion about the naming of hacks. There are some things that I think are necessary, that are requirements, and others that I recommend, that are just suggestions.

I'm going to call this a "label" for the hack, since people have been using the "name" of a hack for different things.

Every release of a hack should have a globally unique label. "Releasing" a hack means that you're publicly publishing a file that has a different file contents than other releases of the hack. To get an globally unique label, use your Arc forum username as a prefix to the label. The prefix doesn't mean that you're the author of the hack, only that you're the one who is publishing it.

(By the way, I checked, and the Arc forum does in fact not let someone sign up with a username that differs only in case from an existing username. So my prefix can be "catdancer").

A hack published under a given label needs to be immutable. An easy way to do this is to add a "release number" 0, 1, 2... to the label. The release number doesn't say anything about the hack; it's just a number to say that a file that has different contents has been published. But using a release number is just a suggestion, not a requirement. You don't have to use a release number if you don't want to, as long as whenever you publish a file with different contents you use a different label.

The label for a hack is like git's SHA-1 for a commit: it's globally unique, and the commit a SHA-1 refers to can't change. But I'm not cryptographically enforcing the immutable requirement, I'm just saying to do it, and a label is something that we can comfortably type.

The label should contain only regular filename characters. I should be able to grab a bunch of different hacks from different people and throw them in a directory using their label as a filename without doing any conversions or creating subdirectories. I should be able to throw them up on a web site and let them be downloaded simply with http://example.com/path/{label}

Once we have an immutable label for a hack, then it's easy to publish information about a hack. We can say that this hack is an alpha, beta, or stable release, that it's better than these previous releases of this hack, that this is the best release of this hack, that it needs feature X to run, that these other hacks provide feature X, that this hack conflicts with those other hacks.

I mostly recommend not putting information about a hack into its label. Because the information you know about a hack may change in time. It's easy to publish new information about a hack, but the label has to stay the same, so you may end up with the label claiming something that is no longer true. But that's just a suggestion. Once you prefix a label with your username, and keep it immutable, you can name the label whatever you want.

1 point by rntz 5672 days ago | link

Using publisher rather than author as the prefix for a patch makes sense. However, upon reflection, I'm not going to rename the tags I published to anarki from "anarki.hack.0" to "rntz.hack.0"; I think using "anarki" as the publisher makes as much sense as using "anarki" as the author. In particular, if I publish a patch as, say "rntz.simplify-halve.0", then it would be rude for someone else to publish a patch as "rntz.simplify-halve.1", because they're not me. So they'd have to do it as, say, "johndoe.simplify-halve.0". But this destroys the sense of progression, from release 0 to release 1. It's the difference between contributing to a project and forking it. By saying that a patch is published by "anarki", a publicly-writable project, I'm inviting people to improve it and release it under the same moniker - the same way anarki itself, a publicly writable community repository, allows people to improve on the works of others. So I think using "anarki" as a community label for publishing patches is still a legitimate idea, because it stands for a useful distinction.

-----

1 point by CatDancer 5672 days ago | link

I think there's no problem with that as long as you have some mechanism that helps people not publish hacks out of Anarki that end up with the same label.

For example, I haven't tried it, but if git prevents me by default (if I don't use a force option or something) from pushing a tag to a repository that already has that tag, and you're using tags for the label, then that would do the trick.

-----

1 point by shader 5672 days ago | link

Are you saying that the label should include the version information? Or is that included in the "information about a hack"?

Let's suppose for a moment (very hypothetical ;) that I had written a new and improved version of ppr, and I had it in a file named ppr.arc. How would you recommend that I publish it?

  http://website/shader.ppr.0.arc
  http://website/shader.ppr.arc
  http://website/ppr.arc

Should I just put it in Anarki? Should I put it in a separate branch?

-----

1 point by CatDancer 5672 days ago | link

If the version information is intended to convey meaningful information (such as major release vs. minor release, alpha vs. stable, etc.), then I'd put that in the information about the hack, instead of in the label.

For publishing a release, I'd personally use http://website/shader.ppr0.arc for the sake of typing less dots, but http://website/shader.ppr.0.arc is fine too.

The way git is normally used by other projects is that files don't contain version or release numbers, and when a release is made a package file is created (a zip or a tar or whatever), that contains the unique version or release number (foo-1.34.03.zip). So, in the same way, you could take a ppr.arc file that you have in git and publish it as shader.ppr0.arc, shader.ppr1.arc, etc.

-----

1 point by Adlai 5672 days ago | link

I agree with everything you've written here. Earlier, I thought that hacks should be entire directories, but now that I think about it more, if a hack spans multiple files, it should probably be broken into multiple hacks (for example, your JSON parser is two hacks -- the parser combinator, and the JSON parser built using the combinator).

How will meta-data be transfered? One option that I can think of is to just put it at the top of the file containing the hack. If it's just a list of data, "compiling" it won't be a problem when the hack is loaded.

However, that doesn't really work for hacks distributed as patches. So, another option would be to have the info distributed as a file with the same name as the hack, but a .info extension (or .meta, or something along those lines).

-----

1 point by CatDancer 5672 days ago | link

How will meta-data be transfered?

Haven't really thought about it yet... :)

One option that I can think of is to just put it at the top of the file containing the hack.

That would prevent the information from being changed, since a hack (with a particular label) needs to be immutable.

So, another option would be to have the info distributed as a file with the same name as the hack, but a .info extension

That would work.

-----