On contributing guidelines

[jodros]

Since SILE has been pretty useful to me for the last months, I'd like to be an usual contributor of this project as a whole - not only the core typesetter, but I'm missing any guidelines to follow. The documentation explains greatly how to extend it for one's own use, but when it comes to actually contributing, it doesn't.

For example:

• which conventions one should follow regarding to:
  • code style
  • creating new commands
  • proposing new packages (e.g. why a package would be accepted as part of the core distribution and when it wouldn't and should be just a external extension via LuaRocks?)

Another important step to do so would be to have a list of the main enhancements desired in README.md, for everyone who had contact with SILE be aware of the needs of the project. I suppose many people use to contribute just adding what they found missing for their own needs, but if someone just wants to do something more, this kind of road map would be great.

As we can see here in the Community standards, besides a general guideline for contributors, we also miss templates for issues and PRs.

[alerque]

I'm glad to hear you've found SILE to be useful, and also that you you want to contribute.

Don't be shy about jumping in. Feel free to work on whatever area scratches your itches. Yes things are a little disorganized as far as how / what folks can contribute. In fact if you feel the lack of some specific guideline perhaps that can be a contribution.

Just a few non-exhaustive notes:

• For coding style, Rust is a non issue because there is only one-true-way-to-format-Rust-code: rustfmt. I miss that in Lua and have even changed my own mind a few times over the years. If you work on something try to match the code around you. Also setting up automatic styling with stylua or similar is something I'd be open to.

• New commands are welcome in existing classes if they are broadly useful. One area that could use some serious work for example is a complete overhaul of the default book class. None of us existing developers are actually using it, we're using our own. Backporting good parts of those into the SILE default would be amazing work. Function proliferation just for the sake of functions might not be such a good thing, but surely there are more that can/should be worked up.

• New core packages are welcome, again especially ones that are core typesetter function that provide good building blocks for more specialized uses. In general we don't want super specialty packages or one that add external dependencies, but will consider proposals. Even if the answer to a proposal or submission is "lets not put this in core" we are also open to hosting semi-official packages in the SILE org and published through official channels to encourage a 3rd party ecosystem where useful stuff is easy to get setup and use.

As for a list of desires / needs: that's what the issue tracker is for, not the README. We have lots of feature requests and know bugs. We also have some issues grouped into projects and have a few issues discussing what the goal are for milestones, such as #1398.

Personally I don't think issue and PR templates are very useful and find them frustratingly restrictive on most projects. They are mostly useful for weeding out low-quality reports that don't include relevant information, but we're not exactly flooded with those at this stage. If you can think of some specific template bits that would be useful to contributors then I'm open to hearing about it.

[jodros]

Thanks for your answer and patience. I admit that firstly I found myself a bit shy about coming here and proposing stuff, like being somewhat annoying by request reviews and/or asking too much... Anyway, since the doors seem to be open, I'll take a look at these projects, make other PRs I've been thinking about and engage more.

I made a PR to the package template (sile-typesetter/package-template.sile#2), unfortunately I made two, because when did the first still didn't know how to fix things I'd like do change without making another PR 🤦, so sorry for have polluted the repo's history. Can you review it?

[alerque]

No worry, we all learn how to do things. But yes you can ammend existing PRs by adding more commits to the same branch and pushing again, or even rewriting history and force pushing the branch. Nothing is considered immutable until it's merged to a protected release branch.

[Omikhleia]

Another important step to do so would be to have a list of the main enhancements desired in README.md

Rather than the README, I'd suggest using the Wiki pages -- also a great way to revive them, and discuss our options.

[Omikhleia]

@jodros @alerque I added a "Contributing" section to the Wiki, with some of the things from this discussion.

On my way, I also reorganized and extended the FAQ (with new items on input formats, etc.)
I also improved a bit the "Equivalent packages" section -- and reorganized a few other minor things as well.

I'm interested in your feedback, and perhaps we can make this Wiki much better and useful!

[Omikhleia]

I have just added a "Regarding questions" to the Contributing guidelines on the Wiki.
In particular, our Gitter channel is not made that much visible elsewhere, is it? I dunno, but I've to say I have felt very lonely on it for a while... ;)

[Omikhleia]

... Also added a FAQ item on overflowing lines, as I've seen this question more than once.

[Omikhleia]

We also have some issues grouped into projects

@alerque Unless I'm mistaken, only organization owners can create "public" project.

Can we possibly get the following projects:

• "Bibliography (Citations)": I opened several issues related to them, it would be nice to keep them grouped
• "SIL syntax": We already have several issues (on spacing problems, on documentation, etc.), which could benefit from being grouped
• "Language": We already have a bunch of linked issues on ICU, BCP47 etc. They already have links to each others (last time I checked), but a project might be useful here too for better tracking

[Omikhleia]

• There are also several issue relating to the frame/pagebuilder/insertions combo -- I would suggest grouping them in a project too. (IMHO, the whole frame/pagebuilder/insertions would need a severe refactor or redesign, but it would help having a view of the scope)