Summer of Code/Acceptance

Revision as of 19:47, 25 April 2013 by Tbrowder (talk | contribs) (Make a patch)

This page is intended to lay out the basic "rules and requirements" that the BRL-CAD project requires of all Summer of Code (whether GSoC or SOCIS) participants whose project proposals are accepted. Unless otherwise arranged with the BRL-CAD project administrator (contact 'brlcad' via IRC on, it will be expected that all students comply with the requirements outlined below.

Application Recommendations

Make a patch

Strictly speaking, this is an optional step to the application process. It will, however, greatly increase your chances of being selected all else being equal if you provide a patch, however trivial, with your application. If you're a final candidate, you can pretty much consider this step required as we will want to see how you code.

We want to make sure that you have rudimentary skills in compiling code, reading other people's code, and can even simply get BRL-CAD to compile. Prepare and submit a patch to our Sourceforge patches tracker.

Don't worry. The patch can be just about anything and doesn't need to be more than a couple lines. Making any trivial patch will be good enough so long as it is can be applied to the BRL-CAD sources with very minimal hassle.

The patch should be something actually useful. The patch should not just be whitespace, indent, or style changes as those are automated periodically. It should be a functional patch such as fixing a known bug (see our BUGS file or sf bug tracker) or implementing some very minor uncontroversial feature (see our TODO file). Bug fixes are generally the preferred scope but even something as trivial as fixing typos or improving a usage statement for an existing command can make an acceptable patch.

This is one of several opportunities to impress us, so feel free to be creative. Be sure to include a link to the Sourceforge patch tracker item in your application. You will need a Sourceforge account in order to post the patch to the tracker.

Come talk to us

You really should be talking to the BRL-CAD developers long before submitting your application. Discuss your ideas with us on the #brlcad IRC channel or on the brlcad-devel mailing list. Communication is a huge part of our evaluation criteria.

We're looking for long-term develepers so we need to be able to know that we can interact and communicate easily with you.

Participation Requirements

License under the LGPL and grant rights

In addition to abiding by all the BRL-CAD HACKING rules and per the Summer of Code FAQ/rules, participation with BRL-CAD requires that any work performed and provided be in accordance with BRL-CAD's existing license (LGPL) and that nonexclusive copyright will be assigned/granted. If your country doesn't allow nonexclusive assignment of copyright, rights to use the code in perpetuity should be similarly granted such that the intent of BRL-CAD's existing license and distribution terms are preservable.

Provide daily progress reports

In addition to any communications you have with a mentor or any of the developers, it will be expected of all students that they will submit a brief progress report of their daily activity. These reports won't need to be more than a sentence or two (or more, whatever is appropriate) but the reports should give an indication of what you did, things you discover, tasks completed, difficulties encountered, milestones reached, days off, and other similar details on your activities. If you did nothing, that's okay! We want to know when you're doing nothing and when you work like crazy.

You will be expected to complete a report that accounts for every day at least once a week, but it's recommended that students update their log daily. Most students don't have a habit of discussing their work adequately and this intrinsically documents progress. Communication ftw. Daily reports are also a great way to let people in the community follow your project and gives students a place to showcase cool in-progress development highlights!

List your milestones

All projects will be required to submit a minimum of three and a maximum of ten milestones for your project. These are not deliverables but, rather, are overall tasks that should be completed throughout the duration of your work. These should be necessary implementation steps and not include any research or familiarity phases. In the end, there is code that must be produced and your milestones should be a (very) rough breakdown for estimating your actual implementation progress. These milestones should be published in your first progress report, that is, at the beginning of code development.

Join our IRC channel and mailing list

All students will be expected to be on the #brlcad IRC channel while they are working and actively engaged on the mailing list so they can be responsive and available for questions, comments, and suggestions from other BRL-CAD developers.

Much of BRL-CAD's open source development occurs over IRC as it is the central gathering forum for core development activities, developer discussions, commit notifications, and more. That said, several mentors will be more readily reached via the mailing list too so the student will be expected to interact on both as needed.

See here if you are new to IRC and need assistance finding a client (or just do a search). If you've never subscribed to a mailing list before and actually need help, you might not want to apply.

Compile and run BRL-CAD

Being able to compile the sources on your own equipment is a very basic task that is generally considered beyond the scope of participation and, as such, will be an expected unassisted capacity of all students. We're more than happy to help you get started the first time if you run into a problem, but you are expected to put forth due diligence effort.

Additionally, understanding the existing user community is very important for most developers to have at least a basic familiarity with. In the end, your changes will (hopefully) be pushed out to the community and you be cognizant of what that will mean.

Be familiar with the basics of Subversion

BRL-CAD sources live in a Subversion repository on Sourceforge. You will need a Sourceforge account and will be expected to abide by the same coding requirements of the other existing developers. You will similarly be expected to know the basics of how to work with SVN and check in changes, resolve conflicts, and apply patches as needed. SVN has a nearly identical interface to CVS -- if you're familiar with CVS, then you should be fine. If you don't have a Sourceforge account, be sure to get one and familiarize yourself with BRL-CAD's sourceforge account. Whether students work on a branch or on the mainline will vary depending on the student and the project.

Evaluate your performance

As performance is something we always strive to keep in mind, quantitatively evaluate your performance and the impact your modifications will make. Don't prematurely optimize and don't over-architect, but also don't make guesses or assumptions either. Use a performance profiler, test your code, add temporary debug timers, have a peer review your approach, etc. Modifications to the code that detrimentally impact performance will likely be rejected outright.

Write maintainable code

This requirement cannot be stressed enough. One of the primary evaluation criteria for all students is how maintainable is the end result. This is not only maintainability from the stand-point of source code longevity as it stands written, but also involves other higher-level maintainability and integration aspects. Does your implementation use interfaces, languages, tools, or techniques that introduce some new requirement to widespread BRL-CAD development? If so, that choice needs to be discussed and justified or otherwise mitigated as a concern. Any usage of external dependencies needs to be consensus approved by the core developers. Is your code comprehensive and comprehensible? Well-documented? Organized? You are required to follow BRL-CAD's existing developer guidelines, existing code style, and established conventions.

Write portable code

BRL-CAD has an extensive heritage of being as portable as reasonably possible with effort continually being taken to make sure the entire codebase works on a vareity of compilation and run-time environments. While each developer's perception of what is reasonable certainly fluctuates over the years and from developer to developer, the general intention is that code written for BRL-CAD should function the same on most moderately popular operating system environments as much as possible including Linux, Mac OS X, and Windows as well as other platforms. It is each developer's responsibility to either make sure their code isn't platform-specific or that equivalent functionality is provided on other maintained platforms. You are expected to interact with other developers when portability issues are raised to resolve any problems. Portability of any dependencies being used must similarly be taken into account and relates to the aforementioned maintainability requirement.

Write complete code

Perhaps treat each week like it is your last. You should be able to hand over functional code over just about any time during development (within a day or so) to another developer. Focus on completing tasks, completing code features, and working on keeping your code functional at all stages of development. That way, no matter how far you get on your milestones or deliverable(s), other developers will be able to review, test, and readily integrate your code. Plan your development approach accordingly. You should generally not "stub" code functionality (though comments are good), but instead focus on coding "deep" instead of "wide". It's generally preferred to have 2 features that work fully, than 5 features that half-work or even 20 features that are all 90% complete.