Subject: MiscKit summary and proposal: stirring up the ashes

From: [email-masked] (Don Yacktman)
Date: Fri, 24 Sep 1993 17:17:03 -0600

Another _very_ long message.  Print this one out and
read it over the weekend when you get bored.  I'm
talking over 350 lines, here.  You have been warned.

Well, we've all been quiet for a few days.  I've been both
horribly busy _and_ I've been thinking about some of the
replies that I've seen here.

Let me recap some of the initial points that need to be
settled...and my current positions and questions.  You'll
note that I've folded many of your ideas into this; if
something was your idea, thanks for the idea.  (I don't
have time to credit everyone here, so refer back to previous
messages if you want to know where various ideas came from.)
What I'm trying to do is summarize and propose a bunch of
policies.  If no one presents significant objections,
these will stand.  Therefore, speak NOW or forever hold
your peace.  Remember that I am human, "born to make
mistakes", and so hope that I've covered all bases, but
if I've made a mistake, or left something out, _please_
let me know so we can get going and started off right!

(1)  Prefixes.  Look at old message to see what some
	of the ideas are.  There have been very few
	votes, so I suppose most of you couldn't care
	less.  :-)  I have decided that "FOO" is out
	because "FOOKit" just plains sounds nasty.
	Because the tendency right now is to call
	this the MiscKit, I lean towared using "Misc"
	as a prefix...MiscString, Misc*...even though
	I know some folks prefer two-character prefixes.
	But "Misc" doesn't look so bad; what do
	people think?  Can we go with this?  Since
	two of the three current authors like this,
	unless there's a good objection to it, we'll
	probably go with it.

(2)  Licensing issues.  This is a mess.  It's very tempting
	to just say "make it PD."  The only problem I have
	with that is that in order for folks to trust the
	code, they need to know it has come from a reliable
	source.  By maintaing a minimum of control I could
	be that source, or anyone who ever took my place,
	if that were to happen.  If it weren't for that
	concern, I'd just go the PD route.  Is there an
	easy way to put this concept into legalese?

(3)  Maintaing source.  I am playing collector, integrating
	things into the kit.  The author of a particular
	object still retains any rights they have; the
	version of the kit will fall under the kit's license,
	however.  Outside of the kit, the original author
	can do what they want with the object.  They also
	will be expected to be that object's "moderator"
	which means they will handle bug fixes, enhancements,
	and so on.  If you contribute a subclass of a
	MiscKit object, you own the subclass, but the
	original object belongs to the original owner.
	This way, I have less to do.  I will only accept
	new versions from the object's "owner" and will
	forward anything else to them, for their perusal.
	All I will do is maintain the whole collection,
	taking the objects and adding them to the kit
	and then making sure they work well in concert
	with other kit objects.  If I detect problems, I
	will NOT change an object myself without first
	running it by the original author; I'll follow
	the rule, too.  This method should keep my load
	reasonable.  Note that an author is free to transfer
	responsibility to anyone else if they don't want
	to deal with it, and just wanted to dump an object
	into the kit.  In that case, we'll take volunteers
	from the mailing list who want to do it.  Each
	object will have a credit in it's source and the
	kit will have a top level file with credit in it
	to list who each object's "owner" is so that
	users can route bug reports and requests
	appropriately.  Also, if I get too busy, I will
	move the moderator's job to someone else.  I
	don't expect this to happen, but I reserve the
	right to do so if need be.

(4)  Commercial apps that use the MiscKit should give
	acknowledgement of the fact.  Since things change,
	asking more (like ftp or email address to be
	given) would be too difficult.  Two questions
	here:  should the company that sells the app be
	required to provide a pointer to where to get the
	MiscKit if requested?  Should this be mentioned
	when they credit the MiscKit in the app?  (I don't
	think that either is necessary, and most companies
	would do it anyway.)  Should they be required to
	provide the kit to anyone requesting it?  (I
	think not, myself.)

(5)  CDROM distributions:  they should ask for permission
	from me, and I can give it.  My main constraint
	will be that the _entire_ distribution be included
	with nothing missing, and un tarred for easy access;
	on a CDROM it shouldn't be tarred-and-compressed.

(6)  Third party distributions:  again, obtain permission
	from me first.  The rule will be like POVRay...up
	to $5 per floppy may be charged, but no more, and
	the distribution should be broken up in such a way
	that a minimal number of floppies is used.  (Right
	now, that means no more than one disk, and will
	continue to mean that for a long time; when I give
	permission, this will be spelled out as the terms
	for the permission.)  Oh, and floppy distribs
	should be in a tar/compress or .pkg format.

(7)  Modified distributions must be labelled as such.  Only
	I will be able to release an official version, to
	avoid confusion.  (That doesn't mean other versions
	can't be released; they just need to be marked as
	such.)  I will keep releases coming as often as
	necessary so that this isn't a problem.

(8)  People who modify the source do NOT have to send the
	mods back to the list; if they do, that's great,
	but it's not a requirement.  (Or to the "owner"
	for that matter.)

(9)  What will be accepted into the kit?  Right now we
	have two types of things:  (1) creative interface
	widgets, all of which should be palettized.  (2)
	abstract things which don't need to be on a
	palette, but it's OK if they are.  Most of the
	current objects are (2), but there's more to add...
	Right now, possible contributions should be
	evaluated on a per-item basis, and hopefully a
	pattern will emerge.  I don't wish to turn anyone
	away, so there is that.  As things unfold, we can
	make a decision about things like whether or not
	the library should be split into several libs, each
	of objects likely to be used together.  Right now
	it's not big enough to matter, but later on, we
	may decide that it's too much to link everything
	into every app.  Now, if we could make a shlib
	out of it, this would be irrelevant, but, well,
	we can't do that.  So for now I'm deferring any
	decisions...so let's get on with what people have
	to contribute.

If you have an object you might like to contribute to the
kit, please post now to the list saying what the object's
name is (class name), a brief description (method names
if you like, but a one paragraph description of it's
purpose and function would be most helpful), and a rough
estimate of when it might be available.  If it is ready
now, NeXTMail it to me at [email-masked].  If you
want to wait until the licensing is finalized, I understand
and that's fine, but I would like to know what we will
be dealing with, contribution-wise, now.  I think these
responses would be of general interest, so post them to the
list, unless you feel really shy, in which case, send it
to me directly.  This call includes classes, categories,
palettes, and any other resource (sound/tiff/whatever)
that would be good to include in the kit.

(10)  For now, it will be up to a developer to make sure
	that any MiscKit resources are included as part
	of an app, in the app wrapper.  Currently, the
	only resource that might be shareable is the tiff
	for the ClockView...which isn't very big.  Thus,
	multiple copies (one in each app with a ClockView)
	is no big deal.  If a _lot_ of resources end up
	being contributed, then we can think about a
	separate /LocalLibrary package to install MiscKit
	resources into.  For now, that's overkill, and
	we won't worry about it.  I appreciate the point
	by Michael Pizolato that resources should be
	encapsulated when they are a necessary part of
	an object.  Until there are enough resources for
	this to be worth the effort, though, I'm going
	to hold off on this.  If (or when) this happens,
	I lean to a MiscKit Installer package that can
	install into /LocalLibrary or ~/Library and
	leave it at that.  (In cases of needing version
	compatability, different subdirectories will be
	used to hold older resources...)  This will be
	implemented so that a user of a MiscKit app sees
	nothing other than a need to install a single
	package.  The MiscKit will handle any and all
	other details automatically.  Someone will need
	to write code to search for the needed resources
	as well.  This is a future project, to be
	undertaken when we find it necessary.  Also,
	a resource in the app wrapper would always
	override a MiscKit shared resource.  Any further
	details of this will be decided upon when we
	have to; until it becomes a problem, I'd like
	to move on to developing objects for the kit.
	(In other words, we'll not discuss this any
	more until we have resources to share!)  I agree
	that it will _become_ important, and needs to
	be thought out very carefully, but right now,
	we'd be wasting time to beat this topic any
	more...how to share resources is not a pertinent
	question until there are resources to share.
	(Note that I understand the arguments for having
	no shared resources whatsoever, and eventually
	we'll need to evaluate both sides.  For now
	I'm advocating status quo, until a change is
	felt to be absolutely necessary.  Status quo
	is no shared resources.)

So, what objects to people want to contribute?  What
resources would your object use that could be shared?
If there's enough, well, we'll take this topic up again.
Right now, it's not worth getting in a tizzy over _one_
tiff!  100 tiffs would be another story... :-)

(11)  Each contributor will be recognized with a top-level
	file in the MiscKit that list who was contributed
	code to each object.  There will also be a file to
	direct people to the "owner" of an object for bug
	reports and such.  At the start of an object's
	code and in it's header will be similar information,
	look at the current MiscKit objects for examples.

(12)  Object "owner's" responsibilities should include the
	following:
	* Accept bug reports.  Fix problems or find someone
		to fix the problems.  We don't want buggy
		code; if it's not really a bug, then...
	* Accept requests for enhancements and other
		improvements.  Note that some suggestions
		won't be to your liking.  Tough.  Even if
		it wasn't your idea, if it's good, consider
		doing it.  If you don't know how, say so
		and ask the list if someone can do it;
		there's no shame in that, and this is a
		community project.  There's no room for
		ego here.  (If you provide a .nib interface
		to an object, say, like a Find panel--which
		is an object I'd like to add to the kit,
		if there's a willing contributor--perhaps
		many different .nibs could be provided as
		examples for developers to pick from.)
		Basically, all I'm saying here is to treat
		requests with respect and welcome them.  I
		know this all sounds like common sense to
		most of us, and we all want to avoid annoying
		other people, but I have had some people
		privately voice concerns to me about this.
		I want this project to be professional and
		well received by the community at large,
		and our own "agreeableness" will play a
		large factor in this.  Hopefully this will
		never actually be a problem.  :-)
	* Accept new code to add to an object.  This is
		optional.  If you don't want to have others
		contribute to your object, that is OK and
		will be noted in the kit's documentation.
		I can't see any real reason you wouldn't
		want to accept other's code, but that's
		a personal decision.  I'll take anything
		people want to send me for my objects. :-)
	* Provide, with the object, a .h and .m file and
		a .rtf class spec.  (Note that the owner
		is expected to keep the .rtf up to date
		with the object itself.  This is important.
		Source code is no substitute for good docs.)
		If you want, and if appropriate, you should
		maintain an IB palette with appropriate
		inspectors, etc.  It is OK to have one
		person "own" an object and another to
		"own" the palette, however, as long as
		both work together to keep in sync.  Also,
		any .nibs (like Find panels, in the example
		above) are to be maintained by the _object_
		owner (not the palette; they only handle
		the IB palette and the inspector...).
		And, they can provide any other necessary
		resources, too, as needed.
	* Supply changes to me to include in the MiscKit.
		Releases of the MiscKit will depend on how
		often you submit changes to me.  I'll try
		and keep the turn around time in the day
		to week range, and I will alert the MiscKit
		mailing list before releases so that you
		can get changes to me before releases.
		Of course, being a freebie project, there
		are no deadlines for _you_:  send me changes
		when you want/have them ready.  I'll make
		releases as they come in, letting others
		add to a particular release if they have
		something ready.
	* The author of the original object holds the
		copyright on that object, and the object
		therefore appears in the MiscKit by
		permission of the copyright owner.  The
		copyright may be transferred to the
		"owner", if someone other than the object's
		author is handling maintenance.  Any code
		submitted and added to the object becomes
		part of the object for legal pruposes and
		therefore legally belongs to the copyright
		owner.  I think this is the most sensible
		way to handle this; it would be too hard
		to have an object with each section (C)
		by somebody else...

(13)  I'd like to have a file at the top level, a sort of
	"to do" list, of suggested enhancements and desireable
	objects that could be worked on.  It can list who
	is doing a particular thing, or say that it's open
	for anyone to work on.

So, if there's an object that you would like to _see_ in
the MiscKit, tell us about it now.  Maybe someone will
volunteer to do it!

(14)  Backward compatibility:  Guaranteed for minor revisions
	but not for major revisions.  Personally, I will try
	for it whenever I can, but, and this is the key:  Do
	not choose backward compatability when it will make
	your design worse.  Better to have good objects than
	lousy ones.  We want these objects to be _the_best_
	free objects in the world, don't we?  As to resources,
	if they aren't shared, it's no biggie.  When (if) we
	go to using shared resources, they will have to be
	backward compatible, and the MiscKit resource directory
	will be structured in such a way that new resources
	will not overwrite the old.  I think that backward
	compatibility will end up being most important with
	regards to resources, and less important on programming
	API (but not too bad to achieve in most cases). So,
	backward compatibility only when it won't interfere
	with progress.  I do NOT want a software equivalent
	of the Intel processor design.  Similiar success would
	be OK, but I don't want us keeping around "crufty
	old code", as it was put, just for the sake of that
	one app that the developer won't recompile...

Well, if I left anything out, left something unclear, or
said something you don't like, let's hear about it so that
I can fix it now.

Over the weekend I plan to take some time out and draft
up a preliminary license and set up a new prefix.  A new
MiscKit will be released early next week, most likely on
Monday, containing these changes.  If you really don't
like "Misc" as a prefix, tell me *_NOW_* before I make
the change!  (Note that I will make my draft license from
the one proposed by Christopher Kane; I liked a lot of
his ideas, as the above message shows, I summed up a lot
of it...)  Also, I realize that some won't get a chance
to object to "Misc" before I release the kit (if I do
it Monday), so if a _real_ good objection comes up after
the fact, I'll consider changing it again.  But, "DAY"
will disapper utterly by next week. (No, not me, just
the prefix.  :-)   )

Later,
-don

[email-masked]                  Nepotism is a relative thing.

---

From: [email-masked]
Date: Mon, 27 Sep 1993 09:33:27 -0400

Scott Anguish wrote
>But this does bring up a question... can everyone agree on the
>basic layout as far as directories go?
>
>	/LocalDeveloper/Headers/misckit
>	/LocalDeveloper/Documentation/MiscKit
>	/LocalDeveloper/Source/MiscKit 

>	/LocalDeveloper/lib
>	/LocalDeveloper/Palettes
>
>are all pretty much supported by NeXT, and thats the way I have
>currently organized things on my drive.   I'm curious how Don has
>stuff organized.  Everyone??

Is the fact that these "are all pretty much supported by NeXT"
documented anywhere?  I know there's something about the compiler
and/or linker search paths including /LocalDeveloper, but I'm unaware
of support for such subdirectories as Documentation and Source.
Here's the hierarchy I prefer (which we use here, and which I also
have duplicated under ~/Developer for my own private work):

   /LocalDeveloper/Apps
      released versions of our own and 3rd party development apps
   /LocalDeveloper/Demos
      demo/prerelease versions of our own and 3rd party dev. apps
   /LocalDeveloper/Examples
      PD examples culled from the net, and our own "experiments"
   /LocalDeveloper/Headers
      released versions of our own and 3rd party headers
   /LocalDeveloper/Libraries
      released versions of our own and 3rd party libs
   /LocalDeveloper/Makefiles
      additions/changes to NeXT-supplied makefiles
   /LocalDeveloper/Palettes
      released versions of our own and 3rd party palettes
   /LocalDeveloper/Projects
      1 subdir each, all related files (src, docs, etc.)

I suppose we're lacking a Source subdirectory, which would be for
third-party (including PD) apps, libs, and palettes for which we
have source (the MiscKit source distribution would go there, for
example).  We have some other subdirectories as well (Misc, for
example - nothing to do with MiscKit) that are less important.  In
addition, /usr/local/lib is a link to /LocalDeveloper/Libraries and
/usr/local/include is a link to /LocalDeveloper/Headers.

I could be confused (easy for me ;-), but I think Scott is proposing
a setup for the source distribution, rather than a setup for Don
or individual contributors to maintain sources.  Anyway, I personally
find it interesting to see how others have their project directories
structured.  The structures I have seen so far that are used by
most serious developers are all very similar.

Thanx,
Michael

P.S.  I think I posted my directory structure once before, but I
      can't remember (I have a one-bit brain with no battery backup
      :-).  Sorry if this is a repeat.

---
[email-masked]
NeXTMail accepted

---

From: [email-masked]
Date: Mon, 27 Sep 1993 10:58:23 -0500

> [re: not getting prefix votes & "Misc" as prefix]

Here's my vote: this sounds good.

> [....]
> (If you provide a .nib interface to an object, say, like
> a Find panel--which is an object I'd like to add to the kit,
> if there's a willing contributor--perhaps many different .nibs
> could be provided as examples for developers to pick from.)

Coincidentally, it was with the idea of contributing my FindPanel
class/bundle that I started the discussion about "allowable
contributions" and shared resources.  I've localized the FindPanel
to several languages; I wondered how this might be packaged for
distribution.  I've also included a simple example application
(which I'd hoped to enhance for future releases) that illustrates
the FindPanel's use.  What about that? I wondered.

Random thought: Should/could example applications be written that
use one or more MiscKit classes to illustrate their use?  Just a
thought.

I don't know what Don means by "many different .nibs could be
provided...".  User interface objects like panels should have only
one "look", imho.  The (and many others have noted this over the
years) lack of a FindPanel in the AppKit has been a big user-
interface hole in nextstep.  I suspect that there will be one in
NS 4.0 (though we won't see this 'til 1995 probably).

I've been holding back, waiting for the dust to settle on the
licensing issue.  The license currently attached to my FindPanel
is less restrictive than licenses discussed here so far; I'm
wary of tacking on unnecessary or burdensome requirements.

> * Provide, with the object, a .h and .m file and a .rtf class
> spec.  (Note that the owner is expected to keep the .rtf up to
> date with the object itself.  This is important. Source code is
> no substitute for good docs.)

And not only docs that are a "list and description of methods",
but explanations as to how to use (or how one might use) the
object are also very important (moreso than a reference I think).

> the MiscKit, tell us about it now.  Maybe someone will

The string class stuff currently in the MiscKit looks nice,
but I think I'd like to see it broken up into a small heirarchy
of classes.  For instance, a constant-and-unique string class
would be nice.  I have a memory-efficient and moderately fast
one (that actually protects the memory the strings are in,
unlike the unique strings created with NXUniqueString())
that I could donate to the MiscKit, and/or incorporate into
such a heirarchy.

Christopher J. Kane
[email-masked]

---

From: Scott Anguish <[email-masked]>
Date: Mon, 27 Sep 1993 15:52:55 -0400

>and/or linker search paths including /LocalDeveloper, but I'm
>unaware of support for such subdirectories as Documentation and
>Source.  Here's the hierarchy I prefer (which we use here, and
>which I also have duplicated under ~/Developer for my own private
>work):

	After I originally mailed that to Don and the list, Don told me that infact lib  
is not searched, so I'm definately going to change mine to Libraries as well.

	It seems logical to put the documentation with the classes.  As for the  
source... I wouldn't consider the MiscKit stuff to be example's as such, so I'm thinking  
that that might be a good place for it.

	The reason I brought that up is that I want to address the issue of hardwired  
Makefiles now, instead of later.

	How things are arranged on anyones machine is their business, I just don't want  
the installation and upgrading of MiscKit to be a hassle.

>or individual contributors to maintain sources.  

	Thats about what I was after.

>Anyway, I personally

	Thanks!  I'm a serious developer now! :-)

--
- Scott Anguish -
[email-masked] (NextMail)
[email-masked] (comp.sys.next.announce submissions)

---

From: [email-masked]
Date: Mon, 27 Sep 1993 16:31:18 -0400

Well, guess I can send this along now....
--------------
(1)  Prefixes.  

	Yeah, "Misc" would do very nicely.  I think the
	main problem people have with prefixes of over two
	letters is one of pronunciation:  a random selection
	of over two letters can be hard to pronounce.  But
	since "Misc" is a one-syllable thing anyways, I doubt
	there should be too much problem....

(2)  Licensing issues.  

	Yech.  I'd agree, though...I don't think PD is
	the route to go.  But don't ask me for the legalese...

(3)  Maintaining source.  

	This sounds reasonable.

(4)  Commercial apps that use the MiscKit:

	Hmm... how about...

	  Required:
	    An acknowledgement of the use of the MiscKit.

 	  It would be nice, but not required:
	    A pointer to where the MiscKit could be found 

		  (in docs or if asked, whatever)
	    Providing source to whoever asks for it

        I think that's basically what was suggested anyways...

(5)  CDROM distributions:  

(6)  Third party distributions:  

	Sounds good to me....(Geez, how many pages of legalese
	will all this be?)

(7)  Modified distributions must be labelled as such.  

	Hmmmm....  *IF* you want to allow these, then
	they should definitely be clearly marked.

	I would prefer to just have people send in additions
	to be included in the official MiscKit.  There'll
	probably be enough versions of the official MiscKit
	lying around eventually that it'll probably be 

	confusing enough without the addition of several
	different versions muddling the picture as well.
	
	If they are allowed, how about say that Don has to
	give permission?  Hopefully that will cut down on
	the number.... and maybe Don can convince them to
	just contribute to the MiscKit instead :-)
	
	mods back to the list:
	
	Agreed.  But mention that it would be really nice
	if they did...  :-)
	
(9)  What will be accepted into the kit?

	Sounds good.  I doubt we'll run into too much
	trouble on this front.

(10)  For now, it will be up to a developer to make sure
	that any MiscKit resources are included as part
	of an app, in the app wrapper.  

	Sounds good too.  Hopefully most things like tiffs
	will be in a palettized class, which if you just use
	the palette (or the whole library...right?) the tiff
	should be already included.  (Correct me if I'm wrong.)

(11)  Each contributor will be recognized

	Sounds good to me.
	
(12)  Object "owner's" responsibilities

	Also sounds reasonable.

	"to do" list
	
	This is probably a good idea too.
	
(14)  Backward compatibility:  

	This also sounds good.  But this means it pays 

	to get it as good as you can the first try.
	As someone mentioned, it would be a really good
	idea to send the class definition to the list first
	to see if anyone has any suggestions.

    I personally prefer /LocalDeveloper and ~/Developer as
  installation directories, mainly because the MiscKit
  is a development tool, not a finished end product like
  an app.  Admittedly though, /LocalLibrary
  and ~/Library are much more likely to exist on a given
  system.  Perhaps an option for either?  I suppose this 

  is the thing symlinks were made for in any event...
    (Is there any way to use Installer.app for this?  Or 

  should we not assume execute access to it?)

    A question here, I guess, is whether we should keep all
  the pieces of the MiscKit together in its own structure,
  or split it up with a /MiscKit subdirectory in every 

  approprite spot:

  LocalDeveloper/Apps
  		/Demos/MiscKit/[all example apps, if any]
  		/Examples/MiscKit/[all .m files, etc]
			(or would ../Classes/MiscKit be better?)
		/Palettes/MiscKit/[all .palette's]
		/Headers/MiscKit/[all .h files]
		/Documentation/MiscKit/[all .rtf files]
		etc...
		
   or

      ../MiscKit/Demos
   		/(Examples | Classes)
		/Headers
		/Documentation
		/Palettes
		etc...
		
	 and just put the /MiscKit subdirectory somewhere like
 	  /LocalDeveloper?

    It definitely should be possible to just include one
  or two of the classes singly without having to drag in
  the whole library.  I'm not sure what the directory structure
  would have to look like, but if I want to include just one
  class I'd like to be able to do it with minimal effort.
  I suppose this is the place where self-encapsulation is 

  important... sometimes, though, it's probably just going
  to be up to the programmer to make sure all necessary files
  are in their project.  Make sure the documentation is clearly
  marked in any situation such as this. 

    I agree (sorry Don) with the school which thinks that 

  every app should  be self-contained, i.e. no dependencies 

  on outside files other than NeXT-supplied ones.  Basically,
  if you write an app using some of these things as a pooled
  resource, and Joe User at xxxx.edu downloads your 

  Excellent.app, they probably won't be able to run it because
  they don't have MiscKit installed.  Most likely, the reaction
  will simply be `bag it' and delete Excellent.app rather than
  go to the trouble to find, download, and correctly install
  the whole MiscKit just to have a couple tiffs or nibs.  It 

  just leaves one more thing to go wrong when.  If it's in the
  app, then you can be sure.
    I can understand the sysadmin tendencies in wanting to save
  disk space in any way, but virtually always the little extra disk
  space needed will far offset all the potential problems
  that could arise.  

Phew.  Well, that's all for now,

Carl Lindberg

+---------------------------------------------------+
|Carl Lindberg           Colgate University  '94    |
[email-masked]                          |
[email-masked]                       |
[email-masked]    (NeXTMail welcome)  |
+---------------------------------------------------+