wanted: :homepage DEFSYSTEM option

[Jean-Philippe Paradis]

Would be nice to have a :homepage "http://example.com/thisproject/" option in DEFSYSTEM, along with the already-existing :author, :maintainer, :description and other useful meta-information options.

[Faré (fahree)]

Well, if there's a :homepage field, next thing you'll want a source-url field, a version-control-system field, and a commit-url field, a cliki-url field, etc.

Before someone does something like that, he should probably talk with Xach from Quicklisp.org and/or other people on #lisp and find what is the Right Thing(tm) to do about that.

I'd rather no code is committed until someone has a good discussion on this topic.

[Zach Beane (xach)]

There's already a :properties option. I would prefer a plist for a less-nested syntax, but the alist works ok.

(defsystem foo
  :properties ((:homepage . "http://www.xach.com/")))

(asdf:component-property (asdf:find-system "foo") :homepage) => "http://www.xach.com/"

[Robert P. Goldman (rpgoldman)]

I am attempting to subscribe Zach to this ticket. Are there other important stakeholders? I have the vague sense that some SBCL hackers would be appropriate, but I don't know who, and I'm reluctant to do a lot of scattershot subscribing.

If we are going to open the meta-information can of worms, here's a question for the community: what should happen if you have a local mirror? That wouldn't change the :homepage meta information (that seems like it's stable, because it's clearly "upstream" like :maintainer and :developer), but some of these others that you are suggesting, Faré, seem like they would be overridden locally (e.g., I hate your CVS repo, so I have my local copy in git, or vice versa). I'd be reluctant to see a lot of local preferences stuff migrate into the source code: that makes merging a nuisance.

[Zach Beane (xach)]

Also, extending ASDF to accept more or different forms of information is trivial. Getting authors to update projects and system definitions is non-trivial. Best not to squander the goodwill of authors on this kind of thing too much.

[Robert P. Goldman (rpgoldman)]

I guess I would propose that we add homepage --- it's common enough and useful enough to make it pass my sniff test for first class citizenship along with license and author --- but exile the rest to the properties, as X/Zach suggests.

Per Zach's second comment, I don't think it's a big deal to add this, since we don't insist on it --- ASDF doesn't insist on very much! It's not like adding this will offend anyone's goodwill since we don't, e.g. issue a warning if some piece of the DEFSYSTEM is not there. A STYLE-WARNING might be nice for things like :license, but that WOULD squander some goodwill...

[Zach Beane (xach)]

The best time to make this change would have been 2004 or so. Now it's just a waste of everyone's time. Even if a project author thinks it's a good idea and wants to use it, they have to wait until their favorite implementation is using a sufficiently-recent ASDF to make it work, and then they have to wait until all their users have upgraded their implementations, too. Unless you want to write a system like this:

(asdf:defsystem foo
  #+asdf-has-homepage :homepage #+asdf-has-homepage "www.xach.com")

Nasty.

Just stick with :properties.

[Robert P. Goldman (rpgoldman)]

Zach, with all due respect, I don't think that the compatibility argument you make here really stands up. In point of fact, ASDF 2 compatibility is already a mess. There are a very large number of features of far greater semantic effect, that cannot be assumed simply on the basis of #+asdf2.

E.g., :around-compile was introduced in October, LOCATE-SYSTEM was exported in November, DEFSYSTEM-DEPENDS-ON only supports loading the class of a defsystem since June, etc., etc.

So I really think that your #+asdf-has-homepage is a strawman: we already have compatibility problems that are way worse than that.

If we want to fix this kind of issue, I think we would be better off freezing the ASDF API at this point, calling what we have got ASDF 3, adding :asdf3 to *features*, then moving all new features to :asdf4, and doing maintenance-only support to the current asdf.

I would like :PROPERTIES better if EVERYTHING was done with properties. But now people will have to say "Oh, :author goes at the top, with :license, but :homepage has to be in :properties..." Also, if we have it in properties, there will be no commonality: someone will do :homepage, and someone else will do :web-page, or :webpage, and the properties won't be so useful. My personal belief is that :homepage (or :webpage) is commonly useful enough that it should be first class meta data. But I certainly concede that this is a matter of personal opinion.

[Zach Beane (xach)]

Those features are likely to be used by a tiny percentage of ASDF users. Most will never know they exist.

Adding homepage (and other) information, however, is a universally useful thing to do.

The very fact that people are likely to want to do it makes it more useful to do it in a backwards-compatible way. And the backwards-compatible way is to do *nothing*! People can adopt this useful practice *today*!

[Robert P. Goldman (rpgoldman)]

I'm afraid that I don't agree with you. I agree that only a tiny percentage of users will PROGRAM with features like DEFSYSTEM-DEPENDS-ON, but the moment someone circulates a really helpful library with a subclass of defsystem, then a large percentage of users will USE it. And it is very difficult to tell which features of ASDF are new and which are old. That's the primary problem, IMO, and I'd rather see if we could fix that, than doing this.

And I don't agree that adding homepage information in an arbitrary number of incompatible ways (i.e, just stuffing arbitrary keys and values into a proplist) is universally useful. A property that I can look up on arbitrary systems is universally useful, but a property that can be keyed differently in arbitrary different systems, is not so useful. If you call it web-page and I call it homepage, let's call the whole thing off!

Would some compromise like this be acceptable: agree on a key that can go in :properties or at the top level. Make an accessor with an agreed upon name. At the top-level, we could push the key value into :properties. This makes the syntax uniform with :author, etc. (which I like), supports backward compatibility (you can just push it into :properties right now, if you are concerned about old versions of ASDF).

Actually, let's think about this some more: is there some general solution to having a bundle of meta-data that will be future-proof? And will keep us from having a jumble of different names for the same properties (including undetected misspellings!)? I'd rather spend a little more time and get something like that than think this hard to just get one property in there!

[Zach Beane (xach)]

I find it's easier to correct bad arbitrary metadata than arbitrary bad ideas enshrined in widely-used libraries.

[Robert P. Goldman (rpgoldman)]

OK, but that's a pretty low bar. Can't we try to do better than choose between the devil and the deep blue sea? I have certainly had unpleasantness arise when the :version metadata, in particular, has been ill-formed.

So I would like to see a framework where we can at least provide support for getting the meta-data to be good. We should strive not to break anything that currently works, but if we can do better, I think we should.

E.g., could we move incrementally towards better use of meta-data? Say we could have meta-data properties that are declared, and that extend the currently agreed-upon set. Anyone who wants to add new meta-data properties could provide some sort of declaration, that would mean that they don't get nagged, but ASDF could spot misspellings. Previous uses of properties and of top-level metadata arguments could be gatewayed into such a framework...

Anyway, we have some leisure to discuss this and not move unless we can make a clear improvement since, as Zach points out, :properties provides rudimentary support for this.

[Faré (fahree)]

A few points to consider about adding :homepage

CON:
* It's more OK to require an ASDF update because your code depends on some new feature (e.g. :around-compile), than to require an update just because you're adding a field of metadata when your code could have otherwise compiled fine.
* Yes, it's nice to have a way to find the homepage, but presumably, if you can read the .asd, you already have the code that you got from somewhere (e.g. quicklisp); that somewhere might be a better place from which to gather metadata.
* Unless with want to &allow-other-keys in defsystem, the :properties is THE place to put non-backwards compatible metadata. Are going to allow a never-ending stream of new keywords that break older versions of ASDF when used, or are we going to design it so it works once and for all?
* If we care so much about uniformity with previous metadata, we could move even have the existing metadata keywords map to accessors of the properties slot rather than have slots of their own.

PRO:
* Still, something like a homepage and/or documentation url might be nice, and even if the feature only becomes widely usable next year, better late than never.
* Early adopters could :allow-other-keys t for backwards compatibility with older ASDFs (ouch).

As for depending on a feature:
* I don't know that we'll ever have an ASDF3. The entire point of ASDF is backwards compatibility, and the way that ASDF does versioning, 3.x is considered incompatible with 2.x, so packages that require 2.x or later will fail. Minor detail perhaps.
* You could have a #+asdf2.22 feature (ugly as it may be) for some decisive minor versions.

Metastrategy:
* I suppose the right thing to do might be to wait for someone to write some code that actually does something with the metadata, and let that person decide how best to represent said metadata?

[Robert P. Goldman (rpgoldman)]

Agreed. I think the interesting issue here is how gracefully to add new features to ASDF --- use of conditional reading is unlikely to work in the current set up --- and that issue is not the one here.

I don't have a lot of energy to add features to ASDF without some strategy for making them safer to use, your follow-up suggests a similar lack of enthusiasm, and Zach strongly opposes adding this feature. This seems to me like a WONTFIX unless someone with more energy offers a patch and a compelling story.

[Faré (fahree)]

Last year I thought there would be no ASDF3 ever, but since I've completely rewritten ASDF in the last two months, there happens to be one. And since I'm having an ASDF3 after all, I added a :website-url initarg for ASDF3, together with other slots.

Until I actually release the damn thing, it's still time to change the name of it, so if you have a strong opinion in favor of :homepage, voice it ASAP.

NB: Until ASDF2 is end-of-lifed, this initarg should be used with #+asdf3 conditionals, and/or the system should explicitly #-asdf3 (error "This system requires ASDF3"), or you should #-asdf3 :allow-other-keys #-asdf3 t in your defsystem, or something.

[Faré (fahree)]

Here is what was released in 2.27:

   :long-name "Another System Definition Facility"
   :homepage "http://common-lisp.net/projects/asdf/"
   :bug-tracker "https://launchpad.net/asdf/"
   :mailto "<email address hidden>"
   :source-control (:git "git://common-lisp.net/projects/asdf/asdf.git")