participating in the community - beyond code: presented by cassandra targett, lucidworks

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

Thank You

@childerelda

ctargett@apache.org