On Tue, 31 May 2016 12:44:00 +0300 Simeon Aladjem <[email protected]> wrote:
> Hello, > > Here are several points that we, at MIRACL, have collected: Is this basically how you've been working at github in the past? If so, it would make a fair startingpoint. > 1. Before starting to work on a contribution > > It is desirable that code contributions will be planned, i.e. either a > contribution is done according an opened issue/ticket, or if not, it > is discussed with the community before starting to work on it. > Architectural matters should be discussed before the work starts and > not after a pull request is submitted. Not every contribution is an architectural matter. Of course substantial changes need to be discussed and reviewed, although a startingpoint for that could be someone's proof-of-concept patch. Raising an issue for a change is common practice, and could be made a project norm. That raises the question of when a patch might be too trivial for that: for instance, a change to comments, or to style/layout, or an optimisation within a single function. > 2. Working on and submitting a contribution > > The typical flow for GitHub would be sufficient as a beginner: > - Fork the repository > - Create a feature branch out of master > - Commit and push changes > - Create Pull Request A good process, but I wouldn't suggest enforcing it on third-parties as it puts a hurdle in the way of contributions from people who don't have github accounts. We should at least also accept patches through jira, subject to review. Either way, the level of review required is a matter we need to agree on. I guess comments in either jira or github will serve for reviewers. > Commit should include only logically related changes, and one commit > for a logical unit should exist. If there are 3 logically unrelated > code changes, then 3 separate commits should exist in the Pull > Request. This would make code reviewing easier. > Commit messages should follow a convention. Agree. Commits should be reviewable. Commit messages need a one-line description to help when searching history at a (much) later date. Also reference any relevant Jira issue, github PR, or on-list discussion thread, and credit any third-party (non-committer) contributor. > 3. Unit-tests > > Unit tests should be provided for reasonable code and functional > coverage. Tests should cover use cases rather than just cover code > lines. Each commit should contain the unit tests that are relevant > for the committed changes. > All the tests should pass before submitting a pull request. Ideally, unit tests belong in the repos with the code and build stuff. > 4. CI > > We consider using the Travis CI tool to automate test and builds. It > is widely adopted in open source projects, especially in combination > with GitHub. Travis CI will automatically run tests on pull requests > and do builds after merging to master. > > I would appreciate any comments on the above. At apache we have automated builds and tests across a range of platforms. Jenkins springs to mind: not sure if alternatives are available. We can ask for that. > -----Original Message----- > From: Patrick Hilt [mailto:[email protected]] > Sent: Friday, May 27, 2016 15:45 > To: [email protected] > Subject: Code contribution process and flow > [chop] > I know some of you have bootstrapped open source projects before. It > would be great getting input and guidance on what has worked and what > hasn't. At this stage any input is a step in the right direction to > keep the momentum of the project going. This isn't quite bootstrapping, because you have existing past practice (unless you're anxious to dump all that)? A guidelines page at the website would no doubt be a Good Thing, or we could also get a project wiki. There are matters where we can 'wing it' as we go. Example, Simeon says unit tests, I say documentation. People just need to flag it up here if code seems to be in danger of departing from those! Things I'd like to deal with now are git/branching policy. Release lines vs Main development line vs Dev branches? Level of review/overview required on different lines? For example, httpd has a trunk branch that any committer can commit to subject to commonsense guidelines, but stable branches (from which releases are taken) that require three people to review before anything can be committed. -- Nick Kew
