How previous Authors should be contacted in case of changing existing docu pages

[dpolivaev]

My recent pull request has triggered a long discussion between @macmarrum and me about this issue.

I suggested that all changes can go live and previous authors can discuss them and revert them later if they discover any issues.

Macmarrum suggested that each change should be communicated over a PR and there is always a waiting time of 7 days to get comments from the previous author. All our ideas can be found at the pull request discussion at #59.

We have not reached an agreement about which policy is better, and therefore I decided that the rules should be defined by the docu writers and that I can accept that I have a different view because I do not participate much in the documentation development.

If you want to discuss the issue and particularly if you disagree with mac's view, check discussion #59 and write a comment. Otherwise, the following rules suggested by Macmarrum in #59 (comment) should be followed:

Would you like all commits to be done through PRs?

PR is important to me when content is changed and I am its author. It would also be beneficial when I change someone else's content and they comment on my PR.
I am fine with other commits going without a PR, assuming that when adding content (to existing or new pages), contributors will make sure to avoid duplication.

Particularly, would you like to have a PR in the following cases:

• adding some new documentation page

I am fine for such changes to go without a PR

• moving some checked and improved page from the attic to the root

If no content is changed (e.g. only links), then I am fine for such changes to go without a PR

• removal of inconsistent information from the existing pages

If the content's author(s) can be identified and are active, then I would like a PR to be created

• minor editorial changes on the existing pages

I am fine with the corrections of typos, misspellings, links to go without a PR

• CSS style changes

If the CSS author(s) or the styled content's author(s) can be identified and are active, then I would like a PR to be created

• Results of work in pairing or ensemble programming (I am going to offer an ensemble programming workshop with a focus on the scripting documentation, I suggested it during the last community event)

If content is changed and its author(s) can be identified and are active, then I would like the author(s) to be notified. This is normally done via a PR. But if the author(s) of changed content are part of the group (pairing or ensemble programming), I see little need for a PR as the authors are already notified.

How would you like to handle the PRs?

• How long should we wait for comments until the PR is merged?

168 hours (7 days * 24h) is a reasonable number, in my opinion. People have their own lives. Creating Freeplane documentation is an after-hours voluntary activity, not a day job. I don't expect people to have time every day, but I think once a week is a reasonable expectation.

• What happens in case of disagreement on parts of the PR, who should have the decision-making power?

This is a new point in the discussion. I need to think about it. In the meantime, maybe you could present your idea to solve this.

• Who is responsible for merging the PRs?

I know that many projects grant collaboration rights only after people have proven to be committed (measured by regular or significant contributions). Some projects require a PR review and approval of at least 1 "trusted user" before merging can be done. In any case, by creating a PR, the submitter proposes changes and promises to see them through until the PR is closed. Therefore the submitter is ultimately responsible for merging; if no collaboration rights, then for chasing a trusted user to merge it for them. Having said that, I am fine with other people merging, as long as the changed content's author's right to comment is honored and all parties agree to go ahead

• What happens if some PR changes parts of documentation written by different authors or modifies the structure?

If the changed content's author(s) can be identified and are active, then the submitter mentions them in PR by username (e.g. @macmarrum) to get their comments.
Regarding structural changes like merging attic and docs into a single docsify instance or splitting attic into new-wiki-initiaitve and old-mediawiki-content, I'd say the topic falls under the project owner's purview (can decide alone or ask other members for their opinions).

• What happens if no one reacts to the PR within 7 days?

The PR can be merged

• Would it be all right if some PRs come from other branches of this repository?

It's fine for me, in the context of the right to comment.
Having said that, I recall the topic being discussed a few weeks ago. Arguments were presented, which lead to the agreement between @dpolivaev, @sifran-github and @macmarrum about using forks instead of branches in freeplane/docs. One of the arguments was that if a public preview of PR changes is to be made available, it can only be done from another repository (given the limitation of one GitHub-Pages instance per repo) → #19 (reply in thread)
If we continue with the fork approach, I'd expect everyone to stick to it, also the people who are granted the right to create branches in freeplane/docs.

Additional thoughts

I propose to consider an author as inactive if they fail to respond to requests for comments in at lest 2 PRs and for over 336 hours (14 days * 24h)