Building an extensive Julia Contributing guide

[logankilpatrick]

@elizavetasemenova this is a GitHub discussion, very similar in nature to Discourse. CC @lilianabs

[elizavetasemenova]

Julia Ecosystem Contributor's guide

Welcome!

The purpose of this document is to help YOU contribute to the Julia Ecosystem. You don't need to be a seasoned developer to help Julia grow and improve.
Anyone willing to contribute will find here a roadmap from zero to hero (or from a hundred to one thousand, if you are a pro contributor already). Both code and non-code contributions are welcome, no matter your level of experience or background.This document aims to help you find out

• how you can contribute to match your skills and interests
• what tools and resources can help you contribute confidently
• where you can find ideas for fixes to propose in your first contribution

Why contribute?

There is a spectrum of benefits to contributing - some more obvious than others. Open source projects rely on contributions from volunteers, enabling them to grow and develop. You will be making a difference to one of the most quickly growing languages, and the future of open-source software as a whole.Benefits of contributing:

• engage with the community
• build a track record of public contributions (e.g.. GitHub)
• build confidence with the language and the libraries
• gain exposure for your library

Types of contributions vary depending on your experience, background, and the nature of your interest in Julia.Types of contributions

• improving documentation,
• sharing your (new) package,
• [does this exist?] review a package submitted
• file a bug report
• write tests
• contributing to core Julia
• contributing to other libraries

and more.

Chose your path

Your next step is to identify which kind of contributor you are. There are multiple paths, some of which cross.Do you want to ...

• Discover
• Connect
  • read code of conduct
  • ask questions on Slack or Discourse
  • engage on Twitter
• Learn
• Build
  • write a blogpost
  • cite Julia
  • report a bug
  • make feature request
  • make pull request
  • review documentation
  • share a use case
  • develop and submit a library
  • include future pans for your library
• Help
  • spread a word about Julia's Ecosystem
  • submit a use case
  • answer questions on Slack and Discourse
  • contribute something that isn't addressed in this guide!

[elizavetasemenova]

Above is the first draft outline.

How to find out about all possible types of contributions and contributors? One source could be watching AMA sessions on Youtube, any more good ideas?

[lbswl]

Also, wanted to ask if we have a style guide for Julia's documentation?

[logankilpatrick]

@lbswl see here: https://docs.julialang.org/en/v1/manual/style-guide/index.html

[lilianabs]

Thank you so much @logankilpatrick! But I was looking for a documentation style guide like this one: https://developers.google.com/style

[logankilpatrick]

Ah, got it, it would be great to have that! The flip side is that in Open source, we really can’t force anyone to follow our guidelines (like google can), but it would be worth putting something like this together!

…

On Jun 17, 2021, at 6:12 PM, Liliana Badillo ***@***.***> wrote:  Thank you so much @logankilpatrick! But I was looking for something a documentation style guide like this one: https://developers.google.com/style — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[lilianabs]

Yes, that makes sense but we could still put together a set of suggestions for contributing with documentation. I'm planning on doing some stuff for Flux but after that I'm more than happy to work on this :)

[logankilpatrick]

Thank you very much!!

[elizavetasemenova]

How do I find contributing opportunities?

If by this point you are convinced that contributing is for you, but don't know where and how to find contributing opportunities, we have collated a couple of ideas for you. For each idea we have provided a list of prerequisites and estimated time to make the contribution.

Find a README file to edit

• pre-requisites: GitHub account, text editor with spell checking (e.g. MS Word, Google docs)
• estimated time: 1h
• steps:
  • pick a Julia package
  • find a typo to fix (e.g. paste the text into Google docs for a spell-check)
  • go through a few green buttons on GitHub to submit your contribution

Find questions on StackOverflow to answer

• pre-requisites: StackOverflow account
• estimated time: depends on the question and your experience
• steps:
  • strategy 1: open Stackoverflow and enter in the search box tag [julia]. You will see a list of most recent questions related to Julia. Surely, if you are interested in a more specific question, e.g. the Plots library, substitute the search term with [Plots.jl]
  • strategy 2: open the JuliaObserver website. Click on 'News' and you will see the list of most recent questions, related to Julia, which appeared on StackOverflow.

Find open issues of packages

• pre-requisites: GitHub account, development tools (installed Julia, an IDE)
• estimated time: from 1h to days and months
• steps:
  • pick a Julia package and open its GitHub page
  • on GitHub, open the 'Issues' tab
  • open an issue and read through the existing discussion
  • participate in the discussion and/or solve the issue

How to find Julia packages

The list of Julia packages, organized thematically, can be found at https://juliapackages.com. Click on the name of the package to discover its website, GitHub repository and further details.

The list of packages, organized alphabetically, can be found at https://github.com/JuliaRegistries/General

How to cite Julia?

For citations, please refer to the research page of Julia.

How to install Julia

What are the IDE options?

[logankilpatrick]

strategy 2: open the JuliaObserver website. Click on 'News' and you will see the list of most recent questions, related to Julia, which appeared on StackOverflow.

Let's not send people to Julia Observer directly, I think this link: https://stackoverflow.com/questions/tagged/julia?sort=RecentActivity&filters=NoAnswers&edited=true is the best place to send folks. Though we should also note that there may not be as much low hanging fruit there given those questions are answered quickly. People could also answer questions on Discourse (we should make the section StackOverflow/Discourse). And, we should point them to #stackoverflow-feed on Slack where they can stay upon to date on new SO questions coming in that way if something they know the answer too shows up, they can help!

[elizavetasemenova]

next chunk of the future document, addressing the question "How do I find contributing opportunities?"

[logankilpatrick]

Awesome, I am going to port some of this over to the website and we can start adding things there

[logankilpatrick]

Added the first page, we can chat via zoom if there's questions around how to add things to the site

[logankilpatrick]

Let's start doing these pages as pull requests so we can comment and chat about individual sections of the doc, otherwise, it's kind of hard to point out things/request changes.

[logankilpatrick]

Live: https://julialang.org/contribute/

[logankilpatrick]

See also here: https://ropensci.org/blog/2021/04/28/commcall-pkg-community/?eType=EmailBlastContent&eId=2e6c362f-9d7f-4b28-a69a-f5b958fc35a1

[logankilpatrick]

We should also add a step by step guide to making a core julia contribution: JuliaLang/julia#41445 (clarifying any ambiguity). This may already be accomplished by Katherine's first pull request guide (which we should definitely link)