(I've cc-ed user ML to gather feedback from users for this email as well.) All, Thank you for your feedbacks, discussions, and suggestions. I have tried to take on board all the feedback from the discussion and I propose the following: # Problem Let me summarize the problems we're facing and propose some solution (which may require voting) in the next section: - Search: The source of truth is in the git repository (Github or asf mirror), however, our issue tracking and wiki systems are different. Therefore any task requires us to move back and forth between these various portals/systems. As an example - a contributor trying to find whether an issue was fixed, requires them to search both JIRA, Github for pull requests or commits (and sometimes the release notes and MLs). - Audience/Platform: From an audience's perspective, the user ML and JIRA issue are for users to be able to reach the community and seek help with a bug or request a new feature. The dev ML, and github PR are ways that developers usually use to fix/address an issue or develop a new feature, and get them accepted towards a release. CWiki is used by both to track articles, documentation and FSs, the docs website hosts docs for install/admin/release notes is user-facing. Both JIRA and Confluence are slow compared to Github. The docs website is a static website and is fast. - Relationship and discovery: Historically, the main reason for having a JIRA id with a PR/commit is to be able to track changes for an open bug and gather such a list in the release notes. It also helps with cross-searching of a PR against a JIRA ticket and searching a JIRA id for possible discussion from an accepted PR. A git commit (for example on github) can also help by telling us which tags or branches the commit was included in, so helps in knowing which version of ACS will have that in. - Behaviours: With the current strict requirement of JIRA ids for each PR, we see these behaviours: (a) many times the author may not engage after sending the PR and may not add a JIRA id causing that PR to get blocked indefinitely, (b) the author would create a JIRA id just for the sake of it with minimal description and not filling all available fields such as affects and/or fix version. After a PR is accepted the JIRA ticket may not be properly closed/resolved to leave us with several open tickets which are in fact close-able. - Pollution: Due to JIRA-caused behaviours 'administrative' changes such as changing of versions, addition of upgrade paths after a version is cut, changes to update the iso url, dependency version in pom.xml etc end up creating '00s of new JIRA ticket. We're already in our 10k numbers. At this point in time it is not likely that all these tickets will be addressed, the workload involved would simply not make this feasible. # Let's discuss Solutions Let me acknowledge here that enforcing any process in the community is a challenge and to some extent not possible in a community of contributors doing work in their *free time*. In an ideal world, I understand we would want all procedures to be followed (as some of mentioned in favour of that) but practically if there are other ways to fix our problems and reduce red-tape we should explore that. Let me propose a comprehensive solution and request your feedback and thoughts: - Search: We've all organically made great progress with higher cadence after switching to a Github based contribution workflow. I hope nobody disagrees how easy it is now to contribute and review, compared to what we did in past with "reviewboard". With the final/ultimate source of truth stored in the git repository, it only make sense to stick to one platform that is easier to use. Github, I think, is usually faster than both ASF jira and cwiki. - Audience/Platform: Based on a query with ASF INFRA, I was adivsed that a project can use all the features of Github (see https://issues.apache.org/jira/browse/INFRA-16186). I also checked and confirmed that any changes to Github repo goes to the commits ML. I propose we stick with Github and for starters explore using the 'github issues' for issue tracking. We may explore wiki and projects in future (or on an experimental basis). Having both issues and pull requests/reviewing on the same platform will make it easier for both users and developers to use one platform for searching, logging, and use. I propose to limit our scope of changes and start with Github issues first. A discussion of moving away from cwiki can be held in future. Historical data in existing systems will be kept for reference, but may be deprecated in the future. The legacy systems can avoid taking new additions, and all users and developers encouraged to use the Github equivalents - Discovery and relationships: As experimented with 4.11.0.0, we can use Github milestone (that are basically CloudStack versions) to track PRs that should go towards a release. Github project boards may also be used to track and triage issues/pull-requests towards a release which especially RMs and co-RMs can use. Users would create an issue in Github, against which a developer can create a PR. If a developer has identified an issue for which an issue-ticket does not exist, they can choose to send a PR directly with all the details and descriptions logged on the PR description. Both Github issues and pull requests can be linked to a milestone, project, some labels, and assignees. I think this approach to the process will reduce a lot of overheads, reduce duplication of description, reduce splitting of information across different information systems. List of changes can be simply related via milestones and release notes can be easily created using the milestone. - Behaviours: We will no longer need to create JIRA ids as a strict requirement. A great deal of work in managing two disconnected portals will be resolved, this will also reduce overhead. A user can log a Github issue. A developer may send a PR against a logged Github issue, or simply just send a PR linked to a milestone (and/or project). Using milestones, we can reference what went towards a release, the same can be used to easily generate issues/changes list for release notes. Because JIRA are mostly used by users to log issues (or due to the strict requirements), usually developers may not follow it regularly and try to fix issues. Github is easy and faster, and having an issues tab (with a count of outstanding issues) can cause more developers to participate in discussions for an open bug (like they do on pull requests). By having issues tracked through Github, users may get more attention from developers. Keep same merge guideline: With the proposed changes, each PR will still require at least two non-author reviews/LGTMs and regression test result OK to get them accepted. So, any confusion (whether additional information, JIRA/Issue IDs are needed) can be left at the discretion of non-PR authors. A pull request template has been recently proposed and accepted for both 4.11 and master branches that will standardize how pull requests are reviewed/sent. # Next Steps? We discuss and rectify the proposal ^^ and if we're positive we can vote and ask the INFRA team to enable issues (and wikis) for cloudstack-* repos on github. Like we did with reviewboard, we can switch to Github issues over time and stop using JIRA/issues while keeping the system accessible for legacy referencing etc. We can update the project website around contribution, and fix the CONTRIBUTING.md in the repository, and update the release process and related articles on cwiki. Thoughts, feedback? Thanks. - Rohit
<https://cloudstack.apache.org> ________________________________ rohit.ya...@shapeblue.com www.shapeblue.com 53 Chandos Place, Covent Garden, London WC2N 4HSUK @shapeblue From: Rohit Yadav Sent: Tuesday, March 13, 2018 2:27:29 PM To: dev@cloudstack.apache.org Subject: [DISCUSS] Relax strict requirement of JIRA ID for PRs All, To make it easier for people to contribute changes and encourage PR/contributions, should we relax the requirement of a JIRA ticket for pull requests that solve trivial/minor issues such as doc bugs, build fixes etc? A JIRA ticket may still be necessary for new features and non-trivial bugfixes or changes. Another alternative could be to introduce a CONTRIBUTING.md [1] that explains the list of expected things to contributors when they send a PR (for example, a jira id, links to fs or other resources, a short summary and long description, test results etc). Thoughts? [1] https://help.github.com/articles/setting-guidelines-for-repository-contributors/ - Rohit <https://cloudstack.apache.org>
