How to submit a pile of documentation patches?

[John Labovitz]

Hello SILE people,

I’ve been spending a fair bit of time learning SILE. Going through the documentation again, I spotted small errors: some typos and spelling & grammatical errors, some typographical issues like the wrong em-dash or quotation marks, some phrases that could be improved for better readability, some formatting errors, and a few areas (like the `lists` package) which I thought needed a bit more extensive help.

I decided to fork the repo and make edits to the .sil files and the .lua files (with the autodocs) as I went along, figuring it was a good way to learn how to write in SILE format. (Before you ask, yes: I’ve been rebuilding the docs for proofing as I make changes.) I’m mostly done, and `git diff --shortstat` says:

> 54 files changed, 690 insertions(+), 663 deletions(-)

Eek! I guess I dove in a little deep…!


I hope you’re interested in the fixes. I’d like to contribute them, but I reckon a single huge PR is probably not the best way to go. Should I do separate PRs, perhaps one for the main docs (in documentation/), and then separate PRs for each modified package or class?

—John

[Didier Willis]

Hello John,

I am not a maintainer, but just a "casual" contributor with PR's too, so don't take my word for granted, but:

• I would recommend a PR or several on SILE's repository (https://github.com/sile-typesetter/sile), since that's where the code happens :)
• Probably split the things that pertain to the manual (documentation/*.sil) in its own PR, since these go well together and are (quite) independent from the rest = for instance as "docs(manual): ..." commit(s) in a PR
• For package documentations (*.lua with documentation strings used by "autodoc"), another PR with "docs(packages): ..." commits, likely. Some packages might have pending PRs so it could be good to check for conflicts before, if doable.

Just my 2 cents, but personally I'd like the docs to better (... having already dabbled into the topic too !)

Regards,

Didier.

[Didier Willis]

By the way:

> (...) and a few areas (like the `lists` package) which I thought needed a bit more extensive help.

I might be the culprit here :)

I could be interested in some of your improvements, if they can make it too in my "extended" list packages(*), since SILE's lists package was kind of a trimmed-down version of it.

(*)  I.e. `resilient.lists` package from 3rd-party package collection resilient.sile (https://github.com/Omikhleia/resilient.sile)

[Caleb Maclennan]

On 2023-02-09 22:33, John Labovitz wrote:
> I hope you’re interested in the fixes.

Absolutely! Documentation fixes, even small ones, are very valuable.

> but I reckon a single huge PR is probably not the best way to go.
> Should I do separate PRs, perhaps one for the main docs (in
> documentation/), and then separate PRs for each modified package or
> class?

From your descriptions it sounds like all the changes are documentation
(copy edits, typesetting issues, and possibly formatting etc.). I'd be
fine with all of that being in one PR. If there are any changes to
behavior that will affect other user's usage (e.g. changes to class or
package behavior not limited to their use is the manual) then maybe
those should be split out in a different PR for review.

What I would like to see is somewhat granular commits with different
types of edits or areas being editing split into different commits.

I will note though that I'm happy to help with that process some. I'm
pretty adept with `git revise` and other tooling to re-hash how the
commit history comes together. If you haven't been splitting things up
and commiting as you go feel free to start out with a lump-sum commit
and PR and we can start splitting things out of it from there.

Caleb

[John Labovitz]

On Feb 9, 2023, at 21:53, Caleb Maclennan <ca...@alerque.com> wrote:

> Absolutely! Documentation fixes, even small ones, are very valuable.

Glad to hear it!

> From your descriptions it sounds like all the changes are documentation (copy edits, typesetting issues, and possibly formatting etc.). I'd be fine with all of that being in one PR. If there are any changes to behavior that will affect other user's usage (e.g. changes to class or package behavior not limited to their use is the manual) then maybe those should be split out in a different PR for review.

There should be no code/behavior changes at all. I’ll admit I haven’t run a test suite, as I’ve installed SILE via Homebrew and not from source. (I tried, but couldn’t get the dependencies sorted out properly.)

> I will note though that I'm happy to help with that process some. I'm pretty adept with `git revise` and other tooling to re-hash how the commit history comes together. If you haven't been splitting things up and commiting as you go feel free to start out with a lump-sum commit and PR and we can start splitting things out of it from there.

Ok, I’ve committed a lump-sum PR, as that’s how I’ve been working. I think if you go through it, each hunk should make sense. However, if you’d like me to try to split it up by task, I can try to do it. But things often overlap: I might fix a spelling error *and* a usage problem *and* a formatting thing in one line, which makes splits harder.

I’ll admit this is my first major PR ever, for any project, I think! I’ve been using git for ages, but embarrassingly never in quite this way. I hope it’s reasonable; if not, just let me know and we can work on it.

—John

[Caleb Maclennan]

On 2023-02-10 01:11, John Labovitz wrote:
> Ok, I’ve committed a lump-sum PR, as that’s how I’ve been working. I
> think if you go through it, each hunk should make sense.

Thanks. We can work on that from there. I'll probably nitpick a few
style guide issues but overall most of the changes looked great so don't
be discouraged. I'll try to get them in by the next release cycle, which
might be a bit latter than usual. My country is dealing with a major
disaster and my kids with major health issues and both are putting me
behind in work, and FOSS stuff behind that.