participating in the community - beyond code: presented by cassandra targett, lucidworks
TRANSCRIPT
O C T O B E R 1 1 - 1 4 , 2 0 1 6 • B O S T O N , M A
Participating in the Community: Beyond Code Cassandra Targett
Director of Engineering, Lucidworks
3
02
4
• Director of Engineering at Lucidworks • manage the Open Source team
• Lucene/Solr committer and PMC member
• Not a programmer
About Me 01
5
Why Contribute to Open Source
Understand Solr Better Improve Your SkillsMake Solr Better
01
My boss won’t let me
I don’t have time
I don’t know enough about Solr
I’m not great with Java
7
• No one knows everything about Solr
• If you are using Solr, you know enough to contribute
Obstacle: I don’t know enough about Solr
8
• Make it easy for yourself to work in short bursts
• Start small
• Feedback (+1/-1) is a contribution
Obstacle: I don’t have time 01
9
• Will take too much of a developer’s time
• Project is not a Core Competency
• “Legal” Won’t Like It
• Can’t let competitors know what we’re working on
• Might expose our Intellectual Property
• Don’t understand how the community works
Obstacle: My boss won’t let me
10
• Who has the objection? Is it your boss or the company?
• Can you take out proprietary stuff?
• Cost of maintenance of customizations locally
• Good citizenship
• Helps build your skills
Possible Counter-Arguments 01
11
• Neither am I
• Solr still needs YOU
Obstacle: I’m not a Java Programmer 01
12
What Tools Can You Work With?
13
• It’s easy to be overly vague (“It’s broke”)
• Concrete feedback is a contribution (“When I do XYZ steps, I get these errors”)
• Can you add anything to advance the problem toward a solution?
• What would make life easier for future users?
What Is a Contribution?
14
• Solr Ref Guide missing lots of stuff • Tutorials
• Getting Started
• Use Cases
• Best Practices
• Changes in recent releases
Documentation
15
• Editing limited to committers
• Comments or JIRA issues are main way for non-committers to contribute
• Online is only for the next release. The PDF is 700+ pages long.
Documentation Today
16
• Docs with Code
• Written with Asciidoc
• Static HTML built with Jekyll and Asciidoctor tools
Documentation Future
17
• Docs with code means ability to submit patches and pull requests
• Online versions for each release
• Online as the primary presentation mode (will still produce a PDF)
Benefits of New Doc System
Link to another page
This page will have a TOC
Comment
Headings
Page title
Italics
All rendering of text, headings, links, etc. managed by CSS
HTML Output
Defines doc attributes, some for output
Include full text of another page
Separate the “book” into parts
Info Blocks
Supported:
WARNING NOTE TIP CAUTION IMPORTANT
Code Examples
Code Callouts
* Other languages use a different syntax for a callout; most use line comment syntax, such as // or #, etc.
Labeled List
Level 1
Level 2
29
• Solr-user list is high-volume, ~1000 mails/month
• Help new users understand how to ask their question
• Identify XY problems
• Point users to documentation or explain terminology
Mailing List & IRC
30
• We need help with issues • 2,807 open issues
• 2,466 opened more than 6 months ago
• Try to reproduce with the latest Solr, provide steps to reproduce if it still exists
Verify JIRA Issues
31
Advancing a Bug Report
Report a Problem
Show Logs & Steps to Reproduce
Write a Test to Reproduce
Find Possible Cause in Code
Provide a Patch
Commit Fix
32
• If an issue has a patch, see if it applies cleanly and helps resolve the problem (and doesn’t cause other issues)
• Tests that prove the problem are so helpful
How Can You Advance an Issue?
33
• 14 Ways to Contribute to Solr without Being a Programming Genius or a Rock Star: https://lucidworks.com/blog/2012/03/26/14-ways-to-contribute-to-solr/
• Solr Example Reading Group: bit.ly/SolrERG
More Ideas
34
• Solr needs more users sharing their experiences
• Your feedback is welcome
• Your contributions are needed
Summing Up