[Caml-list] Project hosting for new OCaml projects

[Caml-list] Project hosting for new OCaml projects

[David Allsopp]

I've got a bit of code in a library which seems worth putting online. I'm
trying to consolidate the steps that should be taken to accomplish that
(beyond simply putting a tarball online!) and wondering if anyone can
confirm if what I've come up with is the "best/obvious" course of action.
Indeed, are there already "idiot"'s guides for this - I couldn't see
anything like it on ocaml.org et al?

So, this particular library is a pure OCaml library, which simplifies things
somewhat. At present it's built using GNU make and of course it is managed
using findlib.

It seems that the following are worth doing:

* Support OASIS (and in so doing, I believe that will migrate its build
system to ocamlbuild)
* Support OPAM (which looks incredibly straightforward - being primarily a
Windows user, the OPAM typhoon has flowed past me thus far)
* Put the SCM online somewhere; submit a pull request for opam-repository;
announce it

So, apart from any obvious errors/omissions in those steps, I have two
questions:

1. What are the differences, politely, in terms of things you can and can't
do between using GitHub and the OCaml Forge for the project pages? The Forge
seems the obvious choice, even ignoring the offensive name of the other!
2. Given that, is there any benefit/different to hosting the git repository
on the Forge vs hosting it on github and simply linking to it from the
Forge?

Thanks!


David

Re: [Caml-list] Project hosting for new OCaml projects

[Simon Cruanes]

[-- Attachment #1: Type: text/plain, Size: 2835 bytes --]

Hi,

First let me insist that this is only my personal view.

Le Wed, 05 Mar 2014, David Allsopp a écrit :
> I've got a bit of code in a library which seems worth putting online. I'm
> trying to consolidate the steps that should be taken to accomplish that
> (beyond simply putting a tarball online!) and wondering if anyone can
> confirm if what I've come up with is the "best/obvious" course of action.
> Indeed, are there already "idiot"'s guides for this - I couldn't see
> anything like it on ocaml.org et al?
> 
> So, this particular library is a pure OCaml library, which simplifies things
> somewhat. At present it's built using GNU make and of course it is managed
> using findlib.
> 
> It seems that the following are worth doing:
> 
> * Support OASIS (and in so doing, I believe that will migrate its build
> system to ocamlbuild)

oasis is very nice in that it centralizes, in a single _oasis file,
everything about the project. In particular, it deals with the META file,
building cmxa, cma, cmxs, etc. It can generate a "configure" and a
Makefile (if you so wish), points to the documentation, the VCS
repository, deals with several libraries (or sub-libraries, see how lwt
does it for instance) and executables, etc.

> * Support OPAM (which looks incredibly straightforward - being primarily a
> Windows user, the OPAM typhoon has flowed past me thus far)

Pretty simple indeed, 3 small files in the opam-repository and you're done.
Also the opam team is quite reactive and helpful with packaging
problems.

> * Put the SCM online somewhere; submit a pull request for opam-repository;
> announce it
> 
> So, apart from any obvious errors/omissions in those steps, I have two
> questions:
> 
> 1. What are the differences, politely, in terms of things you can and can't
> do between using GitHub and the OCaml Forge for the project pages? The Forge
> seems the obvious choice, even ignoring the offensive name of the other!

I think the main advantages of github is that since many people use it,
it's easier to fork/contribute to a project (which is simple because
it's 1/ forking 2/ committing 3/ submitting a "pull request" that can be
discussed online; the patch can be modified as needed, and everyone
commenting the pull request can see it). Also, I prefer the UI, but
some could disagree.

The main issue is lock-in, and it requires an account, but so does the
forge afaik.

> 2. Given that, is there any benefit/different to hosting the git repository
> on the Forge vs hosting it on github and simply linking to it from the
> Forge?

My advice, if you already have a github account, is to use it. Otherwise
I can't tell.

Cheers,

-- 
Simon

http://weusepgp.info/
key 49AA62B6
fingerprint 949F EB87 8F06 59C6 D7D3  7D8D 4AC0 1D08 49AA 62B6

[-- Attachment #2: Type: application/pgp-signature, Size: 819 bytes --]

Re: [Caml-list] Project hosting for new OCaml projects

[Yotam Barnoy]

[-- Attachment #1: Type: text/plain, Size: 3636 bytes --]

The github issue has been discussed on the list recently. Basically, github
blows everything else away with its general ease of use, ease of obtaining
information (graphs etc), ease of contribution, and so on. The consensus
appears to be that the only thing it doesn't do extremely well is track
issues. For a small codebase, though, I think the built-in issue handling
is more than enough. If you want your code to be out there; to get eyeballs
looking at it; and to possibly get other people to contribute, github is
definitely the way to go IMO.

-Yotam


On Wed, Mar 5, 2014 at 10:24 AM, Simon Cruanes
<simon.cruanes.2007@m4x.org>wrote:

> Hi,
>
> First let me insist that this is only my personal view.
>
> Le Wed, 05 Mar 2014, David Allsopp a écrit :
> > I've got a bit of code in a library which seems worth putting online. I'm
> > trying to consolidate the steps that should be taken to accomplish that
> > (beyond simply putting a tarball online!) and wondering if anyone can
> > confirm if what I've come up with is the "best/obvious" course of action.
> > Indeed, are there already "idiot"'s guides for this - I couldn't see
> > anything like it on ocaml.org et al?
> >
> > So, this particular library is a pure OCaml library, which simplifies
> things
> > somewhat. At present it's built using GNU make and of course it is
> managed
> > using findlib.
> >
> > It seems that the following are worth doing:
> >
> > * Support OASIS (and in so doing, I believe that will migrate its build
> > system to ocamlbuild)
>
> oasis is very nice in that it centralizes, in a single _oasis file,
> everything about the project. In particular, it deals with the META file,
> building cmxa, cma, cmxs, etc. It can generate a "configure" and a
> Makefile (if you so wish), points to the documentation, the VCS
> repository, deals with several libraries (or sub-libraries, see how lwt
> does it for instance) and executables, etc.
>
> > * Support OPAM (which looks incredibly straightforward - being primarily
> a
> > Windows user, the OPAM typhoon has flowed past me thus far)
>
> Pretty simple indeed, 3 small files in the opam-repository and you're done.
> Also the opam team is quite reactive and helpful with packaging
> problems.
>
> > * Put the SCM online somewhere; submit a pull request for
> opam-repository;
> > announce it
> >
> > So, apart from any obvious errors/omissions in those steps, I have two
> > questions:
> >
> > 1. What are the differences, politely, in terms of things you can and
> can't
> > do between using GitHub and the OCaml Forge for the project pages? The
> Forge
> > seems the obvious choice, even ignoring the offensive name of the other!
>
> I think the main advantages of github is that since many people use it,
> it's easier to fork/contribute to a project (which is simple because
> it's 1/ forking 2/ committing 3/ submitting a "pull request" that can be
> discussed online; the patch can be modified as needed, and everyone
> commenting the pull request can see it). Also, I prefer the UI, but
> some could disagree.
>
> The main issue is lock-in, and it requires an account, but so does the
> forge afaik.
>
> > 2. Given that, is there any benefit/different to hosting the git
> repository
> > on the Forge vs hosting it on github and simply linking to it from the
> > Forge?
>
> My advice, if you already have a github account, is to use it. Otherwise
> I can't tell.
>
> Cheers,
>
> --
> Simon
>
> http://weusepgp.info/
> key 49AA62B6
> fingerprint 949F EB87 8F06 59C6 D7D3  7D8D 4AC0 1D08 49AA 62B6
>

[-- Attachment #2: Type: text/html, Size: 4495 bytes --]

Re: [Caml-list] Project hosting for new OCaml projects

[Hezekiah M. Carty]

On Wed, Mar 5, 2014 at 10:24 AM, Simon Cruanes
<simon.cruanes.2007@m4x.org> wrote:
>
> >
> > It seems that the following are worth doing:
> >
> > * Support OASIS (and in so doing, I believe that will migrate its build
> > system to ocamlbuild)
>
> oasis is very nice in that it centralizes, in a single _oasis file,
> everything about the project. In particular, it deals with the META file,
> building cmxa, cma, cmxs, etc. It can generate a "configure" and a
> Makefile (if you so wish), points to the documentation, the VCS
> repository, deals with several libraries (or sub-libraries, see how lwt
> does it for instance) and executables, etc.
>
> > * Support OPAM (which looks incredibly straightforward - being primarily a
> > Windows user, the OPAM typhoon has flowed past me thus far)
>
> Pretty simple indeed, 3 small files in the opam-repository and you're done.
> Also the opam team is quite reactive and helpful with packaging
> problems.
>

An additional small benefit to using oasis - oasis2opam, which is
installable from opam, allows you to automatically generate opam
metadata from your project's _oasis file.  Writing out the three opam
files by hand is simple, oasis2opam makes it even easier.

Hez

Re: [Caml-list] Project hosting for new OCaml projects

[Francois Berenger]

On 03/06/2014 03:00 AM, Hezekiah M. Carty wrote:
> On Wed, Mar 5, 2014 at 10:24 AM, Simon Cruanes
> <simon.cruanes.2007@m4x.org> wrote:
>>
>>>
>>> It seems that the following are worth doing:
>>>
>>> * Support OASIS (and in so doing, I believe that will migrate its build
>>> system to ocamlbuild)
>>
>> oasis is very nice in that it centralizes, in a single _oasis file,
>> everything about the project. In particular, it deals with the META file,
>> building cmxa, cma, cmxs, etc. It can generate a "configure" and a
>> Makefile (if you so wish), points to the documentation, the VCS
>> repository, deals with several libraries (or sub-libraries, see how lwt
>> does it for instance) and executables, etc.

OASIS also generates install/uninstall targets, that's nice.

>>> * Support OPAM (which looks incredibly straightforward - being primarily a
>>> Windows user, the OPAM typhoon has flowed past me thus far)
>>
>> Pretty simple indeed, 3 small files in the opam-repository and you're done.
>> Also the opam team is quite reactive and helpful with packaging
>> problems.
>>
>
> An additional small benefit to using oasis - oasis2opam, which is
> installable from opam, allows you to automatically generate opam
> metadata from your project's _oasis file.  Writing out the three opam
> files by hand is simple, oasis2opam makes it even easier.
>
> Hez
>


-- 
Best regards,
Francois Berenger.

Re: [Caml-list] Project hosting for new OCaml projects

[Daniel Bünzli]

Le mercredi, 5 mars 2014 à 16:13, David Allsopp a écrit :
> It seems that the following are worth doing:
>  
> * Support OASIS (and in so doing, I believe that will migrate its build
> system to ocamlbuild)
> * Support OPAM (which looks incredibly straightforward - being primarily a
> Windows user, the OPAM typhoon has flowed past me thus far)
> * Put the SCM online somewhere; submit a pull request for opam-repository;
> announce it

Since your build system is make and that you already have findlib support I wouldn't bother with oasis. Rather use an opam file directly for your package metadata and build instructions and put it at the root of your repository. This allows to robustly support opam pinning workflows which are useful for asking people to test fixes and making pre-releases.  

Regarding the choice between github and the forge. I'd say if you want to be nice to potential contributors prefer github which has a decent user interaction. It's not without flaws, the graphs are generally useless, the pull request mechanism is broken (e.g. it completely muddies history with useless commits) and it's never good to rely on the free as in wine service of a company. If you already have some kind of web space where you can store and push git repos I'd suggest to use github only as a mirror (I can provide you with the steps to do so if you are interested) so that you can more easily switch to something else in case github becomes problematic --- as sourceforge became at one point.

Best,

Daniel

Re: [Caml-list] Project hosting for new OCaml projects

[Daniel Bünzli]

Le mercredi, 5 mars 2014 à 21:10, Christophe Troestler a écrit :
> On Wed, 5 Mar 2014 21:00:40 +0100, Daniel Bünzli wrote:
> >  
> > [...] the pull request mechanism is broken (e.g. it completely
> > muddies history with useless commits) [...]
>  
> P.S. You can always merge using the command line¹ which does not have
> that problem.
>  
> ¹ The URL is provided in the mail Github send you so you do not even
> have to go to the Github site.

Yes, that's what I do. But that's not the only thing that is broken about pull requests.  

I think the mechanism (each pull request is a branch on which you push commits) makes it too easy to get non-logical, incoherent commits. There's a pull request, you ask for corrections. The contributor instead of correcting, amending its commit and force pushing to the branch just adds commits to the branch, which results in a sequence of commits that may not make much sense on your main branch (even worse it may put your project in an intermediate bad state on certain checkouts which is bad for git bisecting). Of course you can always ask people to do the right thing, but I think the actual contribution process should make you do the right thing.  

An example here (not to be mean to this fine individual trying to contribute to the opam repository):

    https://github.com/ocaml/opam-repository/pull/1756

The second commit will make no sense in the history of the opam-repository.  

Best,

Daniel

Re: [Caml-list] Project hosting for new OCaml projects

[Sylvain Le Gall]

On 06-03-2014, Daniel Bünzli <daniel.buenzli@erratique.ch> wrote:
> Le mercredi, 5 mars 2014 à 21:10, Christophe Troestler a écrit :
>> On Wed, 5 Mar 2014 21:00:40 +0100, Daniel Bünzli wrote:
>> >  
>> > [...] the pull request mechanism is broken (e.g. it completely
>> > muddies history with useless commits) [...]
>>  
>> P.S. You can always merge using the command line¹ which does not have
>> that problem.
>>  
>> ¹ The URL is provided in the mail Github send you so you do not even
>> have to go to the Github site.
>
> Yes, that's what I do. But that's not the only thing that is broken about pull requests.  
>
> I think the mechanism (each pull request is a branch on which you push
> commits) makes it too easy to get non-logical, incoherent commits.
> There's a pull request, you ask for corrections. The contributor
> instead of correcting, amending its commit and force pushing to the
> branch just adds commits to the branch, which results in a sequence of
> commits that may not make much sense on your main branch (even worse
> it may put your project in an intermediate bad state on certain
> checkouts which is bad for git bisecting). Of course you can always
> ask people to do the right thing, but I think the actual contribution
> process should make you do the right thing.  
>
> An example here (not to be mean to this fine individual trying to
> contribute to the opam repository):
>
>     https://github.com/ocaml/opam-repository/pull/1756
>
> The second commit will make no sense in the history of the opam-repository.  
>

I also find the UI and workflow for reviewing code not very good (better
than nothing though)

Have you tried Gerrit ?

http://gerrithub.io/

N.B. you can also run gerrit on your server.

If you have time to try it and you think it is a better alternative,
just let us know.


Cheers,
Sylvain Le Gall
-- 
Website:     http://sylvain.le-gall.net/
OCaml forge: http://forge.ocamlcore.org
OCaml blogs: http://planet.ocaml.org

Re: [Caml-list] Project hosting for new OCaml projects

[Daniel Bünzli]

Le jeudi, 6 mars 2014 à 12:55, Sylvain Le Gall a écrit :
> Have you tried Gerrit ?

No, but Richard Jones mentioned a few weeks ago that he was using it for a project and it was "horrible".

Best,

Daniel

Re: [Caml-list] Project hosting for new OCaml projects

[Sylvain Le Gall]

On 05-03-2014, David Allsopp <dra-news@metastack.com> wrote:
> I've got a bit of code in a library which seems worth putting online. I'm
> trying to consolidate the steps that should be taken to accomplish that
> (beyond simply putting a tarball online!) and wondering if anyone can
> confirm if what I've come up with is the "best/obvious" course of action.
> Indeed, are there already "idiot"'s guides for this - I couldn't see
> anything like it on ocaml.org et al?
>
> So, this particular library is a pure OCaml library, which simplifies things
> somewhat. At present it's built using GNU make and of course it is managed
> using findlib.
>
> It seems that the following are worth doing:
>
> * Support OASIS (and in so doing, I believe that will migrate its build
> system to ocamlbuild)

Esp. for pure OCaml libraries, OASIS will provide you with all you need
to generate in one step (e.g. .cmxs, .cmxa on the right arch and not on
the other, automatic generation of your META files with the right
dependencies and version and so on and so forth).

Although if you have a working makefile, that you install .cmxa only on
the right architecture (amd64, i386 and no mips) you should be fine and
won't have to use OASIS.

I am biased here, but OASIS helps me to lower the TCO of 24+
libraries/program with an easy workflow for quick releases (but I am an
OASIS poweruser and probably have access to advanced tools that uses
OASIS).

> * Support OPAM (which looks incredibly straightforward - being primarily a
> Windows user, the OPAM typhoon has flowed past me thus far)
> * Put the SCM online somewhere; submit a pull request for opam-repository;
> announce it
>
> So, apart from any obvious errors/omissions in those steps, I have two
> questions:
>
> 1. What are the differences, politely, in terms of things you can and can't
> do between using GitHub and the OCaml Forge for the project pages? The Forge
> seems the obvious choice, even ignoring the offensive name of the other!
> 2. Given that, is there any benefit/different to hosting the git repository
> on the Forge vs hosting it on github and simply linking to it from the
> Forge?

If you plan to have contribution and want to manage them: GitHub.

For big projects, for which I am expecting contributions, I use GitHub
and the OCaml Forge to distribute tarballs and maintain web pages of the
project.

For smaller project, I only use the OCaml Forge.

Cheers,
Sylvain Le Gall
-- 
Website:     http://sylvain.le-gall.net/
OCaml forge: http://forge.ocamlcore.org
OCaml blogs: http://planet.ocaml.org