Date
1 - 7 of 7
[DISCUSS] Development Process
|
Ted Wilmes <twi...@...>
Hello, I'd like to hear what folks think about development process for JanusGraph. I think it would be helpful if we had some basic guidelines documented. I'll throw a few ideas out to get the brainstorming going. Proposed Functionality and Project Direction ----------------------------------------------------------- Proposed functionality should be discussed on the dev list. If it is a large change (how should we define large?), it should be voted on requiring 3 +1 votes from project committers. I could see one example of a large change as adding a new storage adapter. Bug fixes and enhancements that do not change APIs nor require large amount of refactoring should not require a vote. Pull Requests ------------------- I think the Apache TinkerPop project could be one source of inspiration for our dev processes [1]. For PRs in particular, votes are required before a PR can be merged. 3 votes by committers are required and the submitter can (and usually does) vote for their own PR if they are a committer. Since we have folks tagged as "maintainers" for the different modules of JanusGraph, maybe we could also require one of the votes to come from the relevant module maintainer. On the other end of the spectrum, we could lower the vote requirement or allow for commit than review (CTR), skipping votes altogether. We could also stick with voting but allow for CTR when a committer deems a PR low risk. Thoughts? Ted |
|
|
|
Dylan Bethune-Waddell <dylan.bet...@...>
Hi Ted, Thanks for getting this discussion started - I personally like the idea of following the TinkerPop/Apache Way for accepting/rejecting changes, but I'm not familiar with alternatives so I'm looking forward to hearing from others on that. One thing I will say is that I believe the approval of a specific person should be required at times, but only by the request of the person proposing/committing a "big change", or at the request of another committer so long as that request for a specific pair of eyes on is not vetoed by a 3+ vote from other committers. I'm imagining situations in which the current maintainer is indisposed but should (or shouldn't) look at it, or situations in which the benevolent dictator of such and such feature throws a fit and starts vetoing the will of the people. Mostly joking - but it is my understanding no-one should get benevolent dictatorships in FOSS because sometimes weird things do happen. Regarding new features and design discussions, I like what I have seen on the Mesos JIRA before, where a link is posted in the parent JIRA issue to a public Google Docs design document where editing/discussion can take place. The Google Docs approach for "Technical Steering" seems good to me because it is (a) flexible enough to detail anything, (b) in the public eye, and (c) provides an opportunity for the same kind of line-by-line review/discuss iteration we can do on github for code but can't really do on github for arbitrary documents (that would be crazy... right?). Along the same lines I liked this Google Sheet that WikiMedia produced to compare alternatives when they were looking for a graph database to back their query service after Titan was acquired by DataStax. This would also make the definition of "big change" pretty clear, as we define anything requiring a design doc (complete with 3+ committer vote if requirement of doc in dispute) "big", and everything else not. I could imagine us doing something similar when considering new backends/libraries and such. Generally I like the link-out to Google Docs approach because issues of design are usefully separated from development. We might also want to use JIRA (and apply for an open source license to get it hosted by Atlassian), which I am in favour of because I believe JanusGraph consists of enough moving pieces and sub-projects that in the long run setting it up will benefit us as compared to git issue tracking/management - it is my fear that at some point, what is provided by github (just labels and links mostly, no?) will not be sufficient to properly delineate issues and efforts within the project and migrating to something like JIRA will no longer be trivial, and may even be infeasible after a year or two. What do others think? On Tuesday, January 24, 2017 at 9:18:00 AM UTC-5, Ted Wilmes wrote:
|
|
|
|
Jerry He <jerr...@...>
I like the idea of having a formal 'development process' or 'developer' document for the project. Regarding the process to follow to pull in large features, or regular patches or pull request, I am adding here the policy [1] from HBase. FYI. To quote it: Feature Branches Feature Branches are easy to make. You do not have to be a committer to make one. Just request the name of your branch be added to JIRA up on the developer’s mailing list and a committer will add it for you. Thereafter you can file issues against your feature branch in Apache HBase JIRA. Your code you keep elsewhere — it should be public so it can be observed — and you can update dev mailing list on progress. When the feature is ready for commit, 3 +1s from committers will get your feature merged. Patch +1 Policy The below policy is something we put in place 09/2012. It is a suggested policy rather than a hard requirement. We want to try it first to see if it works before we cast it in stone. Apache HBase is made of components. Patches that fit within the scope of a single Apache HBase component require, at least, a +1 by one of the component’s owners before commit. If owners are absent — busy or otherwise — two +1s by non-owners will suffice. Patches that span components need at least two +1s before they can be committed, preferably +1s by owners of components touched by the x-component patch (TODO: This needs tightening up but I think fine for first pass). Any -1 on a patch by anyone vetoes a patch; it cannot be committed until the justification for the -1 is addressed. I think we can reconcile/merge the Tinkerpop policy and the HBase policy so that we have a simple yet fine tuned one. Thanks, Jerry [1] https://hbase.apache.org/book.html#_decisions |
|
|
|
Jason Plurad <plu...@...>
+1 on design docs for major feature changes. It will help retain the underlying goals and decisions, which will be important as new people join and others roll off. Kafka also requires them https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals
toggle quoted message
Show quoted text
On Wed, Jan 25, 2017 at 3:02 PM Jerry He <jerr...@...> wrote:
|
|
|
|
"P. Taylor Goetz" <ptg...@...>
A couple of points to consider:
+1 policy for commits: A lot of Apache projects have guidelines for how long a pull request must be open before it can be merged. Guidelines typically range from 24-72 hours after opening, or after the last code change commit in the pull request. The idea is that with a community spread out over many timezones, it’s best to let the earth rotate at least once so everyone has a chance to review the change during their working hours. For -1 votes (vetoes) on code changes, a lot of projects specify that it must be accompanied by a justification. Without a justification the veto is invalid. Project Direction: I would suggest a guideline that all decision-making take place on the mailing list (similar to the ASF mantra “if it didn’t happen on an email list, id didn’t happen”). Gitter is fine for informal communication, questions, etc., but any project-related decisions should be brought to the mailing lists. An again, a waiting period for decisions gives everyone in the community a chance to participate. I’m also in favor of some sort of “JanusGraph Improvement Proposal" (JIP) (modeled similarly for Apache Kafka’s KIP process) for large changes. It’s a good way to get community feedback for big changes. Feature Branches: Another idea I support. In Apache Storm we use feature branches as sort of a “distributed pull request” — commit rules are relaxed for those branches, and when the feature is complete and ready to be merged to a main branch, the changes go up for review with the same merge rules as a main branch. Pull Request Templates: It’s good to have guidelines around what information needs to go into a pull request title and description. Otherwise you will inevitably get pull requests with a title like “fix bug” and no description, which forces you to look at the code changes -Taylor |
|
|
|
Ted Wilmes <twi...@...>
Great input, thanks everyone. I think we're all pretty much on the same page. If you guys are okay with it, I'll put together a PR to add some candidate documentation around our policies. I'll hit on: * policy for commits * design docs and project decision making * release policy I'll take a crack at harmonizing the points noted here and within the other referenced Apache projects and then pass it along for review. Thanks, Ted On Thursday, January 26, 2017 at 4:17:41 PM UTC-6, P. Taylor Goetz wrote: A couple of points to consider: |
|
|
|
Ted Wilmes <twi...@...>
A pull request has been submitted for this work: https://github.com/JanusGraph/janusgraph/pull/106. --Ted On Friday, January 27, 2017 at 1:22:16 PM UTC-6, Ted Wilmes wrote:
|
|
|