Improve the process and documentation for "How to Contribute" so that Proposals can be discussed, reviewed and accepted (rejected) before a PR is created
Creating this issue to start the discussion about how we as a community can improve the process and documentation for "How to Contribute", the relevant pages are:
- https://docs.civicrm.org/dev/en/latest/core/contributing/
- https://docs.civicrm.org/dev/en/latest/tools/issue-tracking/#guidelines
This specifically relates to adding new features to CiviCRM core or changing existing features in CiviCRM core (I'll just call these collectively "Proposal"). It could equally apply to CiviCRM extensions, since the approach is the same - just the ecosystem is more distributed.
The current documented process revolves around submitting a PR on Github with the associated code. The problem with this process is it has high potential to be rejected, because no prior process of discussion, review or approval has been sought for the Proposal. When you think about it the current state, it's a bit backwards. So this is incredibly frustrating for people wishing to contribute to the project and a huge waste of time. If the PR never had a chance of being accepted conceptually, then there is no point at all in spending time on writing code, testing it, documenting it etc. PRs cost money to produce and no one likes wasting money!
So the process change I would like to see is to move away from PRs being the initial step for the Proposal. The PR should be the resultant of the Proposal process.
A Proposal should be created in Gitlab (not a PR in Github). The reasoning for the change and the proposed approach for implementing the change should be documented with the Proposal.
The Proposal should be available for review and feedback on Gitlab for a set period of time, 2 to 4 weeks maximum (for example). This step is important, Proposals should not languish, unattended.
At the conclusion of that time, the Proposal should be: Accepted, Rejected or Require Further Review; by a new team (CiviCRM Proposal Team) responsible for reviewing Proposals. This should not be the responsibility of the existing CiviCRM Core Team, which are currently under resourced and over worked. For the CiviCRM Proposal Team, we need new people to step up and own this process, so that the work load can be shared between Proposals and PRs. CiviCRM Core Team should not have to do both processes - we want to reduce their work load. This is why I think establishing a new CiviCRM Proposal Team to review Proposals is fundamental to this improvement.
If the Proposal is Accepted then related PR(s) can be created and they individually can go through the code review process.
The key change here is that the PR(s) for this Proposal will be accepted following passing code reviews. Any debate about the merits of the change or new features should occur on the Proposal, during the Proposal review stage. Not during a review of the PRs.
Proposals are for planning and implementation. PRs are for code management.
This issue has also been raised on separate the discussion being had on this PR, https://github.com/civicrm/civicrm-core/pull/11956#issuecomment-385849221
Thanks @eileen
Let's discuss!