search

coq-community / manifesto

Documentation on goals of the coq-community organization, the shared contributing guide and code of conduct.
Other
68 stars 6 forks source link

Define a set of best practices on how to maintain a project #3

Open Zimmi48 opened 6 years ago

Zimmi48 commented 6 years ago

Meta-issue

These best practices should include how to setup CI (with templates), how to maintain compatibility with various versions of Coq, how to name versions and when to release them, how to create packages (again with templates).

Zimmi48 commented 6 years ago

There should also be a template for the README. All coq-community project READMEs should probably contain a few standardized meta-data (short description, initial authors, current maintainer, license, supported versions of Coq...).

spitters commented 6 years ago

In https://github.com/HoTT/HoTT/wiki we collect a bunch of things that are generated automatically using travis: documentation, graphs, proviola code, ...

If people like it, I hope it's not too hard to adapt it. @jasongross has been very clever in setting it up in travis https://github.com/HoTT/HoTT/blob/master/.travis.yml

It might be an incentive for people to upload packages.

Zimmi48 commented 6 years ago

I didn't know about proviola. It is an interesting tool, but also non-maintained. It looks like a good candidate to join coq-community. @JasonGross WDYT? We can open an issue and label it as looking for a maintainer, and cc the various people who have shown interest (and the initial author Carst Tankink to get consent).

spitters commented 6 years ago

Carst has left academia. He did a postdoc with @gares before. I think it could be good to include it in coq-community.

Zimmi48 commented 6 years ago

OK, I created #16.

langston-barrett commented 6 years ago

On the topic of CI: I think it'd be awesome to create an inclusive CI template/generator for Coq projects, along the lines of https://github.com/haskell-CI/haskell-ci. A pie-in-the-sky feature list:

ejgallego commented 6 years ago

Regarding CI maybe we should just add a couple of pointers to the Docker and Nix documentation for setting up travis.

ejgallego commented 6 years ago

Also an interesting issue for plugins is overlay merging from Coq upstream. As you all know, reactivity is important here; maybe Coq devs should have merge rights on plugins so we can indeed process overlays by ourselves?

Zimmi48 commented 6 years ago

As said somewhere else, in coq-community, this is indeed not a problem to give push rights to some Coq developers.

ejgallego commented 6 years ago

We can indeed do like that, or directly use the bot if we see it fit as you proposed.

Zimmi48 commented 6 years ago

Most of the templates mentioned in this issue now exist in https://github.com/coq-community/manifesto/tree/master/templates. We are still missing something related to documentation (coqdoc, proviola, dependency graphs, webpages...). Regarding the documentation of best practices, I have created https://github.com/coq-community/manifesto/wiki/Commit,-branch-and-release-policies which contains many such pieces of advice. The wiki also contains a documentation page about CI.

palmskog commented 6 years ago

We are still missing templates and practices for static documentation.

The MathComp website could be an example to emulate for projects to host static documents using GitHub's gh-pages mechanism. The main pages could be generated from meta.yml files via mustache templates as for README.md. I also wouldn't mind including PDF pre-prints or notes when this is legally permitted.

Here are some resources that could be relevant:

Zimmi48 commented 6 years ago

Seems like good steps indeed. The math-comp website (the actual link is https://math-comp.github.io/math-comp/) is a nice example indeed.

I also wouldn't mind including PDF pre-prints or notes when this is legally permitted.

If you mean pre-prints of articles associated with the project, I suppose the easiest way is just to link to the PDF hosted at HAL or arXiv when available (rather than copying the file).

palmskog commented 1 year ago

I'm thinking that one way to organize documentation for maintaining projects is as a checklist, possibly organized hierarchically. For example:

Basic maintenance tasks

Advanced maintenance tasks

proux01 commented 1 year ago

Maybe s/suppressed those warnings/silenced those warnings/ but otherwise looks good.