initial draft of 'how changes are made' doc

[phette23]

This is a proposal for a new procedure for merging PRs/changes into this repository. There are a number of PRs built up but we have no community-approved method for handling them. This PR will follow its own "community vote" procedure described towards the end of the document, including a period for open comments and revisions.

[jtmlis]

I disagree with pass or die style of voting where, I would have it stipulated that the points should be voted on one by one. They are many articles in any document, and even a few articles in one clause, such as Item 2 line 9, which we can break into 3 subtopics.

The issue with the following is that since the process already takes a month or so, imagine how long this would take. It is even feasible? I am not sure of the value of the following but thought it best to share. Just food for thought, and my 2 cents.

So imagine a Google form with the text and line number in the document being referenced and under that, have the vote option.

Here is a poor example:

Line 9- Item 2:1: Pull Requests generate their own discussion threads where questions can be asked and changes may be proposed or incorporated. Changes to the PR must be made or approved by its original author(s); if they do not agree with the changes, then the changes are better suited to becoming a separate PR.

a) yes b) no c)abstain

line 9- item 2:2) As with creating PRs, if you are not comfortable commenting on a PR for any reason, you may reach out to the CSS who will do so on your behalf. Once discussion has ended on a PR, indicated by two weeks without a comment or change submitted, the PR is ready to be reviewed.

a) yes b) no c)abstain

[phette23]

@thatjulien thanks for your feedback. Unfortunately, this measure has already passed into the community vote procedure it describes. You can vote here: https://forms.gle/FEAWHA4wLWdffMti9 Sorry, I should have updated this thread when we moved to the vote after two weeks without discussion here or in other Code4Lib forums.

I will say that, if I understand your point correctly, it seems unnecessarily burdensome to vote on every line, broken into even smaller subject units of statements, for each pull request. Then handling documents that have narrative threads or self-referential segments becomes problematic—what happens when one line is passed yet others that refer to it or build upon it are voted down? It opens up the potential to approve an incoherent change.

In any case, I hope the idea in this document that PRs should represent logically related sets of changes is enough to address your concerns. It was certainly my intention to cover similar problems to what you describe—PRs where people feel differently about different segments of the text. We can always, within the discussion surrounding a change, find ways of segmenting it that address your concerns.

[jtmlis]

@thatjulien thanks for your feedback. Unfortunately, this measure has already passed into the community vote procedure it describes. You can vote here: https://forms.gle/FEAWHA4wLWdffMti9 Sorry, I should have updated this thread when we moved to the vote after two weeks without discussion here or in other Code4Lib forums.

I will say that, if I understand your point correctly, it seems unnecessarily burdensome to vote on every line, broken into even smaller subject units of statements, for each pull request. Then handling documents that have narrative threads or self-referential segments becomes problematic—what happens when one line is passed yet others that refer to it or build upon it are voted down? It opens up the potential to approve an incoherent change.

In any case, I hope the idea in this document that PRs should represent logically related sets of changes is enough to address your concerns. It was certainly my intention to cover similar problems to what you describe—PRs where people feel differently about different segments of the text. We can always, within the discussion surrounding a change, find ways of segmenting it that address your concerns.

Yes I agree. well I have voted, and will be in touch. I was simply speaking quite liberally and should of weighed my words more carefully instead. Thank you for the thoughtful and well articulated reply.

[phette23]

This proposal passed with 100% of respondents voting in favor of it. We'll merge it and begin applying it to the other PRs in this repository.