Google Summer of Code - Guidelines at 52°North

---

This page collects general and specific guidelines (or rules) for tasks within the Google Summer of Code at 52°North. If you have any comments please contact Ben and Benjamin (b.graeler@52north.org, b.pross@52north.org).

For Everybody

Organization

• The status of reports and related activites (blog entries, ...) is tracked on a status page in the wiki or in Taiga.io.

Requirements for passing

Formal requirements: We require each team of contributor and mentor (both are responsible) to make sure the following formal milestones are reached.

• Blog posts at beginning, mid-term and end of the project including a timely review by at least on of the mentors. The blog posts together form the overview documentation and links to the posts must be added to the project wiki page.
• Live demonstration of the project, alternatively screen casts, which includes thorough documentation.
  • at mid-term (must not at all be complete - go for quick break throughs!).
  • at the end of GSoC.
• Weekly reports (see below) are submitted on time and checked by a mentor within one day.
• Technical documentation in a step-by-step fashion that allow anybody to pick up the project, meaning that he can start from scratch with an empty workspace and reach the most recent development quickly. This includes a list of user stories or tasks that are not completed but would be the next steps.

Project requirements: In addition, of course the contributor has to work on the agreed tasks (which can be adjusted in an agile manner whenever needed) and for the agreed amount of time. Both mentors and contributor must respond timely to communication and try to create a good working environment to deliver good results on the project.

Software Development

• Scrum rocks!
• On GitHub we recommend to follow the fork & pull development model, see https://help.github.com/articles/using-pull-requests

For Contributors

Project Documentation

You and your mentor are free to choose where you keep your project progress documentation. For example, you can write your project blog on your on existing blog. Or you can use GitHub 's wiki feature.

There is one important limitation: Each project must have one page in the 52°North wiki with the "project information page" contents (see below).

Project Information Page

• Each project must have a single project information page that is in the 52°North wiki.
  • a short description of the project,
  • a short description of the contributor,
  • a list of references to any internal or external pages about the project, such as blogs, developer or user documentation,
  • a summary of the project and it's status at the end of the project, and
  • links to the source code and links to relevant documentation (could be in the 52°North wiki or somewhere else).
• The wiki page must comply with the conventions from the WikiGuide.

Weekly Reports

• Weekly reports are due each Monday evening UTC and must be sent to the GSoC mailing list at gsoc-52n@52north.org.
• Use an explanatory subject containing the words "weekly", "report" and the number of the report at least; and even better also your project name, e.g. "Weekly report no. 1 - super project" or "GSoC report week #1 | Project: a good one".
• Start a new email for each report, do not reply to other student's report emails or to your own email from the week before.
• Follow the mandatory structure, which is "1. Status", "2. Problems", and "3. Tasks for the next week".Do not point to local URLs (like http://192.168.42.17/my/service?request=stuff), but rather deploy a test software to the demo server and reference that or include screenshots (but don't spam other peoples inboxes with 5 MBs of images).
  • Status
    • Start the report by relating to the problems of the last week.
    • Be concise but specific enough to justify at least 40 hours of work you have put into that week.
    • Please keep this short and refer to longer issue descriptions, for example on your project wiki page, if you have to report on major issues.
  • Problems
    • This should be open problems that blocked you from fulfilling a planned task. If you had a problem and solved it already, put it in the status section. If you have ideas how to solve an open issue, make that a task for the upcoming week.
  • Next tasks
    • Keep them in a list and divide them into independent items. This way they are more easy to track.
    • Be specific: "Start implementing X" is not specific enough.
• Avoid spoken language.
• Add hyperlinks if you state that you "looked at libraries x (link), thing y (link), and other project z (link)" > this allows you to be concrete without being to extensive.
• Add your findings in the report, not just what you did. "Looked at library x" is a useless piece of information, but "Tested library x and found it does not provide features f and g that we need so did further search for a suitable alternative" is useful.
• The report can be on the mailing list, on a Wiki page, or in a document - you can choose yourself. In any case, so if you use documents, a blog, or a wiki page, then please send a link to the newest report over the mailing list each monday (no reason to fill peoples inboxes with large attachments).
  • Please stick to one way of writing weekly reports as soon as possible (try out what works in the first couple of weeks). If you do switch, then you must migrate all previous reports to you new method. Mentors and org admins should only have to look in one place to get a complete and good picture of where your project is standing.
  • If you use the wiki for your reports, please add a specific section for tasks for the next week using a headline fomatting and add a new headline of appropriate level for every report so that they show up nicely in the table of contents. Also, do not just link/refer to the task section of the "current" or "previous" week: to ensure traceability over time we happily accept duplicated content.
  • If you use documents, please consider the format you use, because not everybody might have the software to open any format - and while you're at it, consider using a blog or wiki page...

Blog Articles

• Blog posts are due at specific deadlines, with a complete draft which must be reviewed by a mentor being due one week earlier.
• Get yourself acquainted with styles and potential contents of the student blog posts by looking at previous ones: http://blog.52north.org/category/gsoc/
  • Some examples of nice introductiory blog posts:
    • http://blog.52north.org/2013/06/20/trajectory-analysis-in-r/
    • http://blog.52north.org/2012/05/30/dynamic-output-formats-for-the-sensor-observation-service/
    • http://blog.52north.org/2014/05/30/envirocar-ux-design/
  • Examples of mid-term blog posts:
    • http://blog.52north.org/2013/08/02/opensensorsearch-midterm-blog/
    • http://blog.52north.org/2014/06/26/sensor-data-access-for-rasdaman-mid-term-blog-post/
  • Examples of final blog posts:
    • http://blog.52north.org/2012/08/23/demonstrating-exchangeable-encodings-for-sos-a-quantum-leap-for-me/
    • http://blog.52north.org/2012/09/19/on-demand-transformation-of-openstreetmap-data-into-common-gis-formats/
    • http://blog.52north.org/2014/08/17/access-control-ui-for-sos-servers-final-blog-post/
• Log in to the blog website using your regular 52°North account: http://blog.52north.org/wp-login.php
• Contact IT-support@52north.org to have them give you the appropriate role.
• Create a new post (Menu on the left > "Posts" > "Add New") and save it as a draft (you are not able to publish a blog post yourself).
• Writing
  • Start and end with a simple paragraph presenting the big picture, without technical details. The general message must be understandable by laymen!
  • The blogpost does not replace the weekly report and should not be as technical, but should provide anybody (imagine you explain things to a relative who is not in informatics!) a good overview of planned or accomplished goals.
  • Use links extensively to reference other pages (52°North Wiki, Wikipedia) with the details - try to keep the article concise and compelling.
  • The correct name is "52°North", not "52N", "52North", nor "52 North", even if you see these forms on other pages or use them in spoken language.
  • Set the category to "GSoC" and the community/communities that your project is related to. This way the post shows up on community-specific websites.
  • Add tags for the most important keywords of your article.
  • Use the "more" tag if your post is longer than 200-300 words: http://en.support.wordpress.com/splitting-content/more-tag/
  • If you have images in your post, include an image caption and reference the image from the text ("... as shown in the figure...").
  • Add images to the post, e.g. architecture diagrams, use case snapshots, make screenshots of old versions or inspiring other user interfaces - anything that somewhat makes sense and makes the post more visual is allowed!
  • More generic information: http://codex.wordpress.org/Writing_Posts
• Publishing
  • Send an email with a link to the draft (i.e. the URL Wordpress is using when you edit your post) to the org admins, your mentors, and the website admin AnnHitchcook (not community mailing lists, unless you have good reasons to do so) and ask for a review.
  • An editor will check your draft and possibly request some changes. You can edit the draft further until an editor will publish the blog entry for you.
• Using the blogpost
  • Retweet the automatically created message on twitter, think about people you could send this tweet to directly (your teachers showing them what you do, related projects, other developers...) - use the blogpost to create a community around your project!
  • Re-post the entry on your development blog.
  • Send a link to the blogpost to the mailing list of 52°North communities with an interest in that topic and kindly ask for feedback on your work.

For Mentors

• Include roughly 5 hrs/week for mentoring in your schedule for the mentoring period. Be aware that this is not much for the potential gain for your project, as the students are expected to work full time! 52°North staff can support you if you have absences during this time.
• Follow the guidelines in DOs and DON'Ts of Google Summer of Code: Mentor Edition, take a look at the Mentor Manual, or read the quick guide at least.
• Clear tasks are very important for the students to get work done in the beginning - don't count on them being very independent, they probably do not have experience in working with a big legacy software project.
  • A good way to get to know the software is writing some missing integration tests.
  • A good way to communicate your ideas is with image mockups the students can work towards to (in the case of UIs)

Requirements to Mentors

• Mentors are responsible for high quality weekly reports as well as setting and achieving project goals.
• On time submission of evaluations.

Weekly report

Mentors report every week on the same deadline to org admins about the current state of work. In contrast to the formal requirements of the student's reports, this can be an informal with only a couple of sentences how things are going, and they must be submitted using the activity log of the respective card on the mentors Trello board.

Bi-weeky code reviews

Ideally, the mentors are constantly working together with contributor on the code. However, the minimum requirement is that practical code reviews happen at least every other week. Mentors have to run the code themselves, give feedback on coding style etc. and ensure the project is going in the right direction.

The code review can be an email or happen on a Trello board or Wiki page - in any case must the org admins be CCed or notified.

Questions for introductory voice calls with contributors

• Are you aware of the rules and regulations of GSoC (and do not have registered more than once, i.e. with only one email address, are actually a legible contributor, ..) ?
• How many hours do you expect to work on GSoC every day (be honest!)?
• What do you find most interesting about the project (be honest! "getting money" is a valid reason to participate in GSoC) ?
• What do you do for fun?
• What courses did you take last semester?
• How are they related to the project?
• What is your favourite programming languages, and why?
• Why did you pick that project?
• What do you want to learn in GSoC (this year)?
• What is the software project that you are most proud of? Can you send us one (!) link to a particular source code file that you like most?
• Did you use GitHub before?
• Have you hear of fork&pull?
• (if the contributor participated in GSoC before) What did you learn in the last GSoCs?
• What do you want to do for fun over the summer?
• Any trips planned? (taking vacation is fine for both students and mentors, it just should be not too long and planned ahead)
• Do you have any questions to us? (about the project, ...)

Also, if you are unsure about the skills of the contributor, give him the chance to impress you: Open a shared document (Google Doc, Etherpad) and ask him to code in front of you. Just some small code samples. This will help you a lot, since there is a huge difference between going through Java tutorials, and coding on your own.

For Org Admins

• Mentor mentoring
  • Have a regular discussion with the mentors about what they do. Motivate them to do code reviews and take part in the well thought out development process, motivate them to act as teachers.
  • If a mentor does not have to put in 5 hrs. per week, that can (!) be nice, but maybe you can motivate him to simply interact more or do some coding tasks himself.
  • Time spend on a task is not the most important measure - learning and reaching set goals is.