[PROPOSAL] Add docker-based "Hello World" tutorial in-tree for new developers

[Paulo Motta <pa...@gmail.com>]

Hi everyone,

For the Grace Hopper Open Source Day mentoring hackathon [1] on Sept. 16 I
created a short guide to handout to participants interested in contributing
to Cassandra so they could get quickly get started working on LHF tickets.
There were about 5 participants and most of them were able to quickly set
up their environments and have a simple "Hello World" patch running in a
local Cassandra container with the help of this guide.

While no hackathon participant got their patches committed, I considered it
successful that most participants with no prior experience got started
really fast and were able to have a look-and-feel of their patches running
locally.

I would like to propose adding this docker-based quick start guide
on CASSANDRA-18035 [2] and would like to hear your opinions and feedback. A
preliminary patch is available if anyone is interested in reviewing it.

Even though we have extensive development instructions available on [3], I
think these can be quite daunting for newcomers that just want to quickly
hack a simple patch, so I think there is value in providing a more
succinct and hands-on docker-based tutorial in-tree.

I think this guide will be particularly useful to new users that want to
contribute non-distributed changes like vtables and configuration, since
they can easily play around with their patches in a local container
environment.

While I don't think anyone will oppose providing nice instructions to
newcomers, a couple of contention points I can think of in this initiative
are:
a) Shipping a new QUICKSTART.md guide in-tree.
b) Shipping a vanilla Dockerfile in-tree, for local testing purposes only.

Regarding a) if there's any objection to adding a new file, perhaps we
could merge these instructions in the "CONTRIBUTING.md" guide, or
alternatively add them to the website documentation.

Regarding b), while we already maintain a docker image in cassandra-builds
[4], that is more targeted to automated testing. I don't expect a
significant maintenance burden for this in-tree image since it's mostly
targeted at manual local testing, but we should make sure we warn users
that this Dockerfile has no guarantees and should not be used in production.

Let me know what do you think,

Paulo

[1] - https://ghc.anitab.org/programs-and-awards/open-source-day/
[2] - https://issues.apache.org/jira/browse/CASSANDRA-18035
[3] - https://cassandra.apache.org/_/development/index.html
[4] - https://github.com/apache/cassandra-builds/tree/trunk/docker

Re: [PROPOSAL] Add docker-based "Hello World" tutorial in-tree for new developers

[Jon Haddad <ru...@apache.org>]

I like this suggestion and I'd take it a step further.  I think the project should be publishing docker images.  If we manage to migrate to Gradle this would be pretty trivial as the jib Gradle plugin is excellent and makes creating and publishing Docker images really easy.

https://github.com/GoogleContainerTools/jib

I think there's an improvement over a local Dockerfile as we'd probably ditch that as soon as we started publishing our own Docker images. 

My 2 cents.  What do you think?

Jon

On 2022/11/10 22:14:15 Paulo Motta wrote:
> Hi everyone,
> 
> For the Grace Hopper Open Source Day mentoring hackathon [1] on Sept. 16 I
> created a short guide to handout to participants interested in contributing
> to Cassandra so they could get quickly get started working on LHF tickets.
> There were about 5 participants and most of them were able to quickly set
> up their environments and have a simple "Hello World" patch running in a
> local Cassandra container with the help of this guide.
> 
> While no hackathon participant got their patches committed, I considered it
> successful that most participants with no prior experience got started
> really fast and were able to have a look-and-feel of their patches running
> locally.
> 
> I would like to propose adding this docker-based quick start guide
> on CASSANDRA-18035 [2] and would like to hear your opinions and feedback. A
> preliminary patch is available if anyone is interested in reviewing it.
> 
> Even though we have extensive development instructions available on [3], I
> think these can be quite daunting for newcomers that just want to quickly
> hack a simple patch, so I think there is value in providing a more
> succinct and hands-on docker-based tutorial in-tree.
> 
> I think this guide will be particularly useful to new users that want to
> contribute non-distributed changes like vtables and configuration, since
> they can easily play around with their patches in a local container
> environment.
> 
> While I don't think anyone will oppose providing nice instructions to
> newcomers, a couple of contention points I can think of in this initiative
> are:
> a) Shipping a new QUICKSTART.md guide in-tree.
> b) Shipping a vanilla Dockerfile in-tree, for local testing purposes only.
> 
> Regarding a) if there's any objection to adding a new file, perhaps we
> could merge these instructions in the "CONTRIBUTING.md" guide, or
> alternatively add them to the website documentation.
> 
> Regarding b), while we already maintain a docker image in cassandra-builds
> [4], that is more targeted to automated testing. I don't expect a
> significant maintenance burden for this in-tree image since it's mostly
> targeted at manual local testing, but we should make sure we warn users
> that this Dockerfile has no guarantees and should not be used in production.
> 
> Let me know what do you think,
> 
> Paulo
> 
> [1] - https://ghc.anitab.org/programs-and-awards/open-source-day/
> [2] - https://issues.apache.org/jira/browse/CASSANDRA-18035
> [3] - https://cassandra.apache.org/_/development/index.html
> [4] - https://github.com/apache/cassandra-builds/tree/trunk/docker
>