CONTRIBUTING.md

How to Contribute

Welcome to OCaml.org's contributing guide. Thank you for taking the time to read it! Your help with OCaml.org is extremely welcome. We are particularly motivated to support new contributors and people who are looking to learn and develop their skills. If you get stuck, please don’t hesitate to ask questions on discuss or raise an issue.

This guide documents the best way to contribute to the project when adding things listed below in Contributing Content. If you're looking for a guide on how to setup the project and suggest a change to the code, you can refer to our HACKING guide, which will also give instructions on how to rebuild the website, if necessary, when making changes.

• Good First Issues: if you are either new to the repository or still getting started with OCaml in general, issues marked as a good first issue are ideal.
• Suggesting Changes: most of the site content is stored in the data directory as Markdown or YAML. To suggest a change or update this content, you can edit those files directly and rebuild the website, detailed in the HACKING guide. This will promote the content into their .ml counterparts. If you would like to suggest entirely new website content or code, please open an issue to discuss it first.
• Implementing Pages: most pages are implemented in src/ocamlorg_frontend/pages using the .eml templating preprocessor. This is mixture or OCaml and HTML.

Reporting Bugs

We use GitHub issues to track all bugs and feature requests. Feel free to open an issue over here if you have found a bug or wish to see a feature implemented.

Please include images and browser-specific information if the bug is related to some visual aspect of the site. This tends to make it easier to reproduce and fix.

Contributing Content

We've provided a list of community-driven content below. When adding content to any of these sections, it's best to fork the repo, add your file, and open a pull request (PR).

• The Blog
• Job Board
• Success Stories
• Academic and Industrial Users
• OCaml Books
• Community Meetups
• Upcoming Events
• Featured Packages
• The OCaml Changelog

The following sections give more details on how to contribute to each.

Add an RSS Feed to the Blog

Anyone can contribute to the OCaml Blog, which is composed of two types of content:

• Community blog posts fetched from RSS feeds
• Original blog posts linked from original source

Fetched from RSS Feed

If you write about OCaml and have an RSS or Atom feed, you can add your feed to data/planet-sources.yml.

When compiling, the feed entries will be downloaded, and Markdown files for each item will be created in data/rss. For instance: building-ahrefs-codebase-with-melange.md`.

Please, make sure your feed only contains articles about OCaml.

Link Original Blog Post

To contribute a link to your original blog post (under OCaml Community Blog), you can add a new Markdown file in data/planet/-individual_external_links/.

Create an .md file with the following header:

---
title: title of your self-hosted post here
description: one-sentence description
url: direct URL to your original blog post
date: 2023-06-13  (this format)
preview_image: direct link to preview image
---

Add an Entry to the Job Board

Contribute to the Job Board.

The job board displays OCaml job opportunities.

To add a new entry to the job board, you can add it to data/jobs.yml.

Please make sure that the job involves mostly writing OCaml. Contributions to add jobs unrelated to OCaml, or where OCaml is a negligible part of the job, won't be accepted.

If you notice that a job opportunity is outdated (e.g., already fulfilled or not open anymore), PRs to remove it are welcome as well.

Add a Success Story

Contribute to the Success Stories.

You can contribute a new success story by adding a Markdown file in data/success_stories/. For instance: janestreet.md.

The success stories should be structured in the following way:

• An overview of your company
• The challenge you faced and solved
• The solution you implemented, which should describe the role OCaml played in solving the challenge
• A post-mortem describing the results you had after implementing the solution

You can read Ahref's success story for an examplary success story.

Add an Academic or Industrial User

Contribute to the Academic Users and Industrial Users.

You can add a new academic user by creating a new Markdown file in data/industrial_users/. For instance: cryptosense.md.

You can add a new industrial user by creating a new Markdown file in data/academic_institutions/. For instance: cornell.md.

Add a Book

Contribute to the OCaml Books.

You can add a new OCaml book by creating a new Markdown file in data/books/. For instance: ocaml-from-the-very-beginning.md.

Add A meetup

Contribute to the Community Meetups.

You can add a new community meetup by adding it to the YAML file data/meetups.yml.

Add an Upcoming Event

Contribute to the Upcoming Event.

You can add a new upcoming event by creating a new Markdown file in data/events/.

Add a Featured Package

Contribute to the Featured Packages.

To update the list of Featured Packages on the Packages page, you can update data/packages.yml

OCaml Changelog

The OCaml Changelog is a feed of the latest releases and feature highlights for official OCaml projects. As of today, it features the following projects:

• The OCaml Compiler
• OCaml Platform Tools

Before a release of the above tools land on the opam-repository, the release manager of the project opens a pull request (PR) on OCaml.org with an announcement for the release.

The announcement is proofread by the OCaml.org team, who will also suggest highlighting release features.

To contribute to a new release announcement or feature highlight, add a Markdown file in data/changelog/.

Git and GitHub Workflow

The preferred workflow for contributing to a repository is to fork the main repository on GitHub, clone, and develop on a new branch.

If you aren't familiar with how to work with Github or would like to learn it, here is a great tutorial.

Feel free to use any approach while creating a PR. Here are a few suggestions from the dev team:

• If you are not sure whether your changes will be accepted or want to discuss the method before delving into it, please create an issue and ask.
• Clone the repo locally (or continue editing directly in GitHub if the change is small). Checkout out the branch that you created.
• Create a draft PR with a small initial commit. Here's how you can create a draft pull request..
• Continue developing and feel free to ask questions in the PR if you run into obstacles or uncertainty as you make changes
• Review your implementation according to the checks noted in the PR template.
• Once you feel your branch is ready, change the PR status to "ready to review."
• Consult the tasks noted in the PR template.
• When merging, consider cleaning up the commit body.
• Close any issues that were addressed by this PR.