Continuous documentation

[17o2]

The aim of this branch is to advance in parallel to the dev branch as PRs are merged and features added.

This can include expanding the syntax description (syntax.md), the changelog (CHANGELOG.md), the general readme (README.md) or others.

Before a release, this branch can be then squashed and rebased onto dev to reflect all the updates included in that release.

The idea is to prevent cluttering the commit history with individual commits from each PR documenting itself (Add #xxx to changelog, Expand syntax description to reflect new feature from #yyy). It remains to be seen whether this is a good idea, and I am open to feedback on this topic.

[kvid]

Please consider including what @JelmerT suggests in #213 (comment).

[17o2]

Looking to merge #214 and #219, I'm wondering whether it makes sense to

• keep this feature/documentation branch, and potentially ask PR contributors to submit an additional PR with the updated documentation as I've done in Add bgcolor attribute to connectors and cables #219

or whether to

• revert back to having the documentation for a new feature updated as part of the PR that implements the feature itself.

I'm starting to lean towards the latter, since this way, the documentation in the dev branch will always be up to date, and it reduces the number of PRs in case the PR author writes the documentation themselves (since I cannot put as much work into the project as I want right now, this will be the case more often than not).
If there are no objections, I would squash-merge this branch into dev and proceed to request updated documentation as part of relevant PRs.

[kvid]

Looking to merge #214 and #219,

Why not consider #197 before these?

I'm wondering whether it makes sense to

• keep this feature/documentation branch, and potentially ask PR contributors to submit an additional PR with the updated documentation as I've done in Add bgcolor attribute to connectors and cables #219

or whether to

• revert back to having the documentation for a new feature updated as part of the PR that implements the feature itself.

I'm starting to lean towards the latter, since this way, the documentation in the dev branch will always be up to date, and it reduces the number of PRs in case the PR author writes the documentation themselves (since I cannot put as much work into the project as I want right now, this will be the case more often than not).
If there are no objections, I would squash-merge this branch into dev and proceed to request updated documentation as part of relevant PRs.

Making a choice that can reduce your amount of work seems like a good idea.

Whatever you choose, I suggest updating CONTRIBUTING.md with a description of if/how the contributors are expected to update the CHANGELOG.md and other documentation affected by the PR.

[17o2]

Why not consider #197 before these?

I did not mention it here since it is does not affect the documentation (as far as I understand).

Making a choice that can reduce your amount of work seems like a good idea.

Whatever you choose, I suggest updating CONTRIBUTING.md with a description of if/how the contributors are expected to update the CHANGELOG.md and other documentation affected by the PR.

A good compromise would be to ask contributors to update any syntax documentation themselves if necessary, but to keep CHANGELOG.md updated by whoever actually merges a PR into dev.

[kvid]

Why not consider #197 before these?

I did not mention it here since it is does not affect the documentation (as far as I understand).

You are right.

Making a choice that can reduce your amount of work seems like a good idea.
Whatever you choose, I suggest updating CONTRIBUTING.md with a description of if/how the contributors are expected to update the CHANGELOG.md and other documentation affected by the PR.

A good compromise would be to ask contributors to update any syntax documentation themselves if necessary, but to keep CHANGELOG.md updated by whoever actually merges a PR into dev.

In that case, I guess you still want a continous PR for the change log similar to this PR?

[17o2]

In that case, I guess you still want a continous PR for the change log similar to this PR?

Yes, see #228.