Set up rules

[CsatiZoltan]

To minimize admin works, it is important to lay own the rules for using and contributing to the repositories. It is especially important as the added material continuously grows. My idea is to declare so-called "essential" and "soft" rules. Essential rules are expected to be followed to maintain the basic structure of the repositories. On the other hand, soft rules are rather guidelines containing recommendations of common sense. Here comes a preliminary set. Feel free to edit and append. There is a related project too. I propose that we first agree in the rules broadly before typing them to the corresponding Readme and Wiki pages.

Essential rules

• [ ] Do not create new repositories. If not, seek everyone's approval it on the chat before creating it.

• [x] Do not create a new folder in an existing repository unless

  • your contribution consists of several files

  • or you are sure that this is really a new topic

  • If in doubt, ask other people in the main room.

The rationale behind the first two rules is that moving files with git messes up the log. Plus your contribution probably already fits in an existing repository/directory.

• [ ] Do not upload anything illegal

• [ ] Prefer text files to binaries

  • Very small files (e.g. tiny png-s) are fine to be versioned.
  • Output files (e.g. *.pdf,*.exe) should not be in the repository, unless users may not be able to compile it (e.g. fontastic.pdf) or there is no way to store it remotely and permanently. Alternatives:
  • use a cloud-based permanent storage (e.g. imgur)
  • use git LFS
  • to be discussed in details

Soft rules

• [ ] Folder naming conventions (to be agreed). Make it explicit, avoid things like test2-v4.cc
• [ ] Coding conventions (do not be restrictive: most files are from individuals, no coding convention is needed unless working in a team)
  • Keep it minimal to the intended purpose (e.g. the SPI cover template needs cleaning up
  • comment everything not obvious (and even then)
  • if your file needs unusual compilation (to be defined), mention it at the top (e.g. LuaLaTeX, index, very recent versions of whatever)
• [ ] If (part of) your solution uses sources, always cite them

Once these rules are accepted and implemented, the corresponding checkboxes should be ticked.

[sylph1o]

Nice issue. I am in a bit of a rush, so here are, briefly, my first thoughts.

1. I propose to change "Do not create new folders" to "create only bottom-level folders". It is not always possible to put everything in one file, so one folder per document (or example, or whatever) can help navigation. To create a folder at an upper level, one should discuss it with the others (e.g. by opening an issue)
2. Precision about binaries: output files (e.g. PDF) should not be in the repository, unless users may not be able to compile it (e.g. fontastic.pdf). Even then, there must be a better way.
3. Coding conventions:
   1. Keep it minimal to the intended purpose (e.g. the SPI cover template needs cleaning up)
   2. comment everything not obvious (and even then)
   3. if your file needs unusual compilation (to be defined), mention it at the top (e.g. LuaLaTeX, index, very recent versions of whatever)

[CsatiZoltan]

@sylph1o

1. That is what I meant. I was not clear.
2. Agree.
3. Agree.

[neerby]

@CsatiZoltan I find all your suggestions quite exhaustive and satisfying, except for the second essential rule. I think a new folder is needed if more than one file need to be committed. Combined with @sylph1o 's item (1), it would make a fair rule. As for soft rules, items (2) and (3) totally make sense to me as well. Finally, I suggest as a soft rules a few hints for commit message format. We could use these short and effective quidelines, and summarize them like that guy did for example.

[CsatiZoltan]

@neerby

I think a new folder is needed if more than one file need to be committed.

Of course. I was not precise.

[Reclu]

I completely agree with all of your suggestions. I just have one (obvious) comment about item 1 of soft rules "Folder naming conventions": it is better if files names are explicits so that names like test2-v4.cc are avoided

[sylph1o]

I suggest to add to 2 something along the lines of "If you create a folder, do not create sub-folders unless absolutely necessary". I have yet to imagine a case where that would be "absolutely necessary"; maybe with a great number of files (e.g. >50).

@neerby, I agree about commit guidelines. What you linked is well-thought, and I think that it should be ever simpler in our case: a few simple rules, then one or two examples.

Where should we put these rules? Here are a two ideas:

1. In Meta's wiki, and every repository's README links it. Thus the information is centralised and easy to maintain.
   2. In every repository's README, which allows the rules to be tailored to every repository and makes those repositories self-sufficient.

[neerby]

I believe that the Meta.wiki is the superior location choice, but we could/should also add a link in every main README. edit: just realized that this is precisely what you suggested first. Agreed!

[CsatiZoltan]

@sylph1o, @neerby My idea is the following: Make use of Github's contribution guidelines support (see also #1), i.e create a new CONTRIBUTING.md file in the Meta repository. The advantage is that whenever somebody wants to create an issue, it will pop-up. What Baptiste said: I also thought of putting a link to this contribution into every README (to the very beginning, so that users see it and do not skip).

[CsatiZoltan]

@sylph1o

In Meta's wiki, and every repository's README links it. Thus the information is centralised and easy to maintain.

I think these rules apply to all the repositories, so I opt for this.

[sylph1o]

@neerby, @CsatiZoltan I agree with the both of you.

[neerby]

I edited the first post to take the discussion into account. We can probably start implementing the CONTRIBUTING.md.

Then links can be added in Getting-started wikipage and main READMEs.

Addition

I would like to take the occasion to formalize the format guidelines for READMEs and wikis after the discussion we started on gitter. Would that belong to this issue ? Or should I start another one?

[sylph1o]

@neerby It sounds like a discussion as big as this one. If this is the case, it would be worth another issue (in which this one could be referenced).

[neerby]

Nice job, thanks again.

Tiny remark:

Moreover, moving files with git messes up the log and gives extra work to the admin.

I suggest to remove "to the admin" since every member is an admin. It gives the impression that some people have more rights and duties than others.

[CsatiZoltan]

Ok, I will remove it when the next version is ready.