Import Upstream version 20180207

[hcoop/debian/mlton.git] / doc / guide / src / MLtonLibraryProject.adoc

MLtonLibraryProject
===================

We have a https://github.com/MLton/mltonlib[MLton Library repository]
that is intended to collect libraries.

=====
  https://github.com/MLton/mltonlib
=====

Libraries are kept in the `master` branch, and are grouped according
to domain name, in the Java package style.  For example,
<:VesaKarvonen:>, who works at `ssh.com`, has been putting code at:

=====
  https://github.com/MLton/mltonlib/tree/master/com/ssh
=====

<:StephenWeeks:>, owning `sweeks.com`, has been putting code at:

=====
  https://github.com/MLton/mltonlib/tree/master/com/sweeks
=====

A "library" is a subdirectory of some such directory.  For example,
Stephen's basis-library replacement library is at

=====
  https://github.com/MLton/mltonlib/tree/master/com/sweeks/basic
=====

We use "transparent per-library branching" to handle library
versioning.  Each library has an "unstable" subdirectory in which work
happens.  When one is happy with a library, one tags it by copying it
to a stable version directory.  Stable libraries are immutable -- when
one refers to a stable library, one always gets exactly the same code.
No one has actually made a stable library yet, but, when I'm ready to
tag my library, I was thinking that I would do something like copying

=====
  https://github.com/MLton/mltonlib/tree/master/com/sweeks/basic/unstable
=====

to

=====
  https://github.com/MLton/mltonlib/tree/master/com/sweeks/basic/v1
=====

So far, libraries in the MLton repository have been licensed under
MLton's <:License:>.  We haven't decided on whether that will be a
requirement to be in the repository or not.  For the sake of
simplicity (a single license) and encouraging widest use of code,
contributors are encouraged to use that license.  But it may be too
strict to require it.

If someone wants to contribute a new library to our repository or to
work on an old one, they can make a pull request.  If people want to
work in their own repository, they can do so -- that's the point of
using domain names to prevent clashes.  The idea is that a user should
be able to bring library collections in from many different
repositories without problems.  And those libraries could even work
with each other.

At some point we may want to settle on an <:MLBasisPathMap:> variable
for the root of the library project.  Or, we could reuse `SML_LIB`,
and migrate what we currently keep there into the library
infrastructure.