Some thoughts: Really great to get this out -- thanks for starting it!
Frankly, it's been a while since I've used TRAC much, but I think gitHub's Pull Request system provides some great opportunities to better manage changes to a document. IN the above, I see ideas like "Once agreed to in the issue, the change can be implemented and submitted as a pull request". But I think it makes more sense to go early with a PR. Often, the text itself what needs to be discussed -- so having the discussion directly in context of the suggested changes to the text has real benefits. PRs support general discussion of the PR, as well as line-by-line comments specific text. This combination is ideal for many suggested changes to the doc. So I suggest something like this: ### Issues: If there is a general issue about the standard that isn't specific to text, like "I suggest we support his new concept in CF" then that should be in an issue. If someone notices and error, inconsistency, missing detail, etc, but does not have a suggested change to the text, that should be an issue. ### Pull Requests: In short -- go to a PR earlier rather than later -- as soon as someone has specific suggestions for changes to the text itself, that should go in a PR. Any typo or minor correction should go straight to a PR. PRs and issues can be pretty easily linked, so the transition is not bad -- if someone submits a PR that requires a larger discussion unlinked to any particular text -- it's not hard to start an issue and link to it. Similarly, if it starts as a issue, it's easy to link to a PR once one is created. ## Potential Problems / Questions ### Making it easy for newbies Creating an issue is significantly less of a technical burden than a PR. That is, pretty much anyone with no experience with gitHub or text-based markup can probably figure out how to submit an issue. PRs, on the other hand, require more tech know-how -- gitHub makes it pretty easy to automatically create a fork for you if you try to edit a repo you don't have access to, but it's still a bigger lift to wrap your head around. So people should be encouraged to submit an issue if they have something to contribute (like correcting a typo, or...) that maybe *should* be a PR. A more experienced developer can make the PR later. ### What do "core" contributors do? People without write permissions to the repo need to create a fork to make a PR. But folks with write permissions to the repo have three choices: 1) make a change directly and push it. 2) make a branch, make the change in the branch, and submit a PR for the change 3) make a fork into their personal account, and make a change and PR from there. I personally prefer (2) as a core contributor to projects. (1) should only be used for the simplest of changes like typos, etc. Some folks prefer (3) as a more robust way to control the process, but It makes more work, and we're all volunteers here, so we want it to be as easy as possible to improve the doc. In particular, (2) makes it much easier for multiple people to work together on a change -- rather than making PRs against forks againsts forks.... Just my thoughts, having worked on multiple gitHub projects, some large, and some small, some as core contributor, some not. -- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: https://github.com/cf-convention/cf-conventions/issues/130#issuecomment-382802993
