Should we have recommended project structure?

[anton-trunov]

A number of projects have a structure like the following one:

.
├── CHANGELOG.md
├── LICENSE.md
├── Makefile
├── Makefile.coq.local
├── README.md
├── _CoqProject
├── foo.opam
├── default.nix
├── dune-project
├── meta.yml
└── theories

Others just have every file in the project root directory or some adhoc directory structure.
Of course, it's not possible for all projects to have the same structure, but I think having a recommended structure, especially for small projects, might help with context switching during maintenance.

If you think it could be beneficial to have a recommended project structure then where do we put it? The template repo's README.md? Wiki? Or somewhere else?

Incidentally (or maybe this should be a standalone issue): having an informal template for _CoqProject file would also help, I think.

[Zimmi48]

The manifesto's wiki seems like the right place since it's already used to document other existing conventions.

[anton-trunov]

Thanks for the suggestion, I'll try to have a go at it and will post the link here.

[anton-trunov]

Ok, here you go, an initial draft: https://github.com/coq-community/manifesto/wiki/Recommended-Project-Structure. I took the liberty of recommending some particular choices, e.g. the default choice of CI I put in is Travis CI. This may not be accurate, but I think something has to be recommended anyway. Please feel free to correct any mistakes I made and add more information. I was aiming at newcomers who are not very familiar with the Coq tools and decided to explicitly add some "obvious" things which are folklore in the hope it'll be useful for some.

@Zimmi48 @palmskog @erikmd please have a look. Any feedback is very welcome!

[Zimmi48]

Good point on having to recommend something. I am of the impression however that we should switch to recommending GitHub Actions instead of Travis CI soon (if not now). The only issue is that we don't (yet) have templates for the GitHub Actions setup using Nix. See also what I wrote in #69.

[anton-trunov]

Fully agreed! I hesitated in favor of GitHub Actions for a bit, but Travis CI is currently used in many community projects. I guess we should switch at least some of them, see how things go and change the recommendation.

[palmskog]

I also agree with @Zimmi48 regarding GitHub Actions. The main reason to go with Travis right now is to have the option to build with Nix in CI. However, this is not a strong reason for many projects, and we could hopefully add Nix CI based on GitHub Actions later on.

[Zimmi48]

@anton-trunov Should we close this issue now?
@palmskog Should the index.md file be added to the recommended project structure? (Under resources/?)

[anton-trunov]

Yes, closing this issue sounds fine to me.