Skip to content

Edit Contributing ReadMe #1323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 22, 2023
Merged

Edit Contributing ReadMe #1323

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e422a53
Update CONTRIBUTING.md
christinerose Jun 19, 2023
daa0148
Update CONTRIBUTING.md
christinerose Jun 19, 2023
8104919
removed PPX & OMP
christinerose Jun 22, 2023
84bad56
Clarified where to put a new blog post
christinerose Jun 22, 2023
8ca60a9
Clarifying contribution instructions
christinerose Jun 22, 2023
c9b6686
Removed Translating Content
christinerose Jun 22, 2023
dfbc748
Fixed inaccuracy about blogs
christinerose Jun 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 59 additions & 64 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,145 +1,140 @@
# How to contribute
# 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](https://discuss.ocaml.org/) or [raise an issue](https://github.com/ocaml/ocaml.org/issues/new).

Welcome to Ocaml.org's contributing guide.
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](./HACKING.md) guide, which will also give instructions on how to rebuild the website, if necessary, when making changes.

This guide documents the best way to contribute to the project. If you're looking for a guide on how to setup the project and submit a contribution, you can refer to our [HACKING](./HACKING.md) guide.
- **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](./HACKING.md) 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](https://github.com/ocaml/ocaml.org/issues) to discuss it first.
- **Implementing Pages**: most pages are implemented in `src/ocamlorg_frontend/pages` using the [.eml templating preprocessor](https://aantron.github.io/dream/#templates). This is mixture or OCaml and HTML.

Thank you for taking the time to read the contributing guide. Your help with Ocaml.org is extremely welcome. If you get stuck, please don’t hesitate to [ask questions on discuss](https://discuss.ocaml.org/) or [raise an issue](https://github.com/ocaml/ocaml.org/issues/new).
## Reporting Bugs

We are particularly motivated to support new contributors and people who are looking to learn and develop their skills.

- **Good First Issues**: issues marked as a `good first issue` are ideal for people who are either new to the repository or still getting started with OCaml in general.
- **Fixing or Suggesting Content**: most of the content for the site is stored in the `data` directory as markdown or yaml. To fix this content you can edit those files directly and rebuild the website. This will promote the content into their `.ml` counterparts. If you would like to suggest entirely new content please open an issue to discuss it first.
- **Implementing pages**: most pages are implemented in `src/ocamlorg_frontend/pages` using the [.eml templating preprocessor](https://aantron.github.io/dream/#templates). This is mixture or OCaml and HTML.
- **Translating content or pages**: for now we are focusing on getting OCaml.org ready for launch and will add more information about translation later.

## Reporting bugs

We use GitHub issues to track all bugs and feature requests; feel free to open an issue over [here](https://github.com/ocaml/ocaml.org/issues/new) if you have found a bug or wish to see a feature implemented.
We use GitHub issues to track all bugs and feature requests. Feel free to open an issue over [here](https://github.com/ocaml/ocaml.org/issues/new) 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
## Contributing Content

Here's a list of the content that is community driven and how you can contribute to it:
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](#content-blog)
- [The job board](#content-job)
- [The success stories](#content-success-story)
- [The academic and industrial users](#content-user)
- [The OCaml books](#content-book)
- [The community events](#content-event)
- [The featured packages](#content-package)
- [The Blog](#content-blog)
- [Job Board](#content-job)
- [Success Stories](#content-success-story)
- [Academic and Industrial Users](#content-user)
- [OCaml Books](#content-book)
- [Community Events](#content-event)
- [Featured Packages](#content-package)
- [The OCaml Changelog](#content-package)

### <a name="content-blog"></a> Add an RSS feed to the blog
The following sections give more details on how to contribute to each.

### <a name="content-blog"></a> Add an RSS Feed to the Blog

> Contribute to the [OCaml Blog](https://ocaml.org/blog).

The blog is composed of two type of content:

- Community blog posts fetched from RSS feeds.
- Original blog posts.
- Community blog posts fetched from RSS feeds
- Original blog posts

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

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

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

To contribute an original blog post (refer to as News on the site), you can add a new markdown file in [`data/news/`](/data/news/). For instance: [`multicore-2021-12.md`](data/news/multicore/multicore-2021-12.md).
To contribute an original blog post (under [OCaml Community Blog](https://ocaml.org/blog) on the site), you can add a new Markdown file in [`/data/planet/ocamlorg`](/data/planet/ocamlorg/). For instance: [`about-utop.md`](data/planet/ocamlorg/about-utop.md).

If you want to re-publish an blog post you previously posted on Discuss, you can fetch it using Discuss API:
If you want to republish an blog post you previously posted on Discuss, you can fetch it using the Discuss API:

```
curl https://discuss.ocaml.org/raw/<id> > data/news/<fname>.md
```

Where `<id>` is the ID of the Discuss post.

### <a name="content-job"></a> Add an entry to the job board
### <a name="content-job"></a> Add an Entry to the Job Board

> Contribute to the [Job Board](https://ocaml.org/jobs).

The job board displays OCaml job opportunities.

To add a new entry to the job board, you can add it to [`data/jobs.yml`](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.
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 opened anymore), PRs to remove it are welcome as well.
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.

### <a name="content-success-story"></a> Add a success story
### <a name="content-success-story"></a> Add a Success Story

> Contribute to the [Success Stories](https://ocaml.org/success-stories).

You can contribute a new success story by adding a markdown file in [data/success_stories/](data/success_stories/). For instance: [janestreet.md](data/success_stories/en/janestreet.md).
You can contribute a new success story by adding a Markdown file in [data/success_stories/](data/success_stories/). For instance: [janestreet.md](data/success_stories/en/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.
- 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](https://ocaml.org/success-stories/peta-byte-scale-web-crawler) for an examplary success story.

### <a name="content-user"></a> Add an academic or industrial user
### <a name="content-user"></a> Add an Academic or Industrial User

> Contribute to the [Academic Users](https://ocaml.org/academic-users) and [Industrial Users](https://ocaml.org/industrial-users).

You can add a new academic user by creating a new markdown file in [data/industrial_users/](data/industrial_users/). For instance: [cryptosense.md](data/industrial_users/en/cryptosense.md).
You can add a new academic user by creating a new Markdown file in [data/industrial_users/](data/industrial_users/). For instance: [cryptosense.md](data/industrial_users/en/cryptosense.md).

You can add a new industrial user by creating a new markdown file in [data/academic_institutions/](data/academic_institutions). For instance: [cornell.md](data/academic_institutions/en/cornell.md).
You can add a new industrial user by creating a new Markdown file in [data/academic_institutions/](data/academic_institutions). For instance: [cornell.md](data/academic_institutions/en/cornell.md).

### <a name="content-book"></a> Add a book
### <a name="content-book"></a> Add a Book

> Contribute to the [OCaml Books](https://ocaml.org/books).

You can add a new OCaml book by creating a new markdown file in [data/books/](data/books/). For instance: [ocaml-from-the-very-beginning.md](data/industrial_users/en/ocaml-from-the-very-beginning.md).
You can add a new OCaml book by creating a new Markdown file in [data/books/](data/books/). For instance: [ocaml-from-the-very-beginning.md](data/industrial_users/en/ocaml-from-the-very-beginning.md).

### <a name="content-event"></a> Add an event
### <a name="content-event"></a> Add an Event

> Contribute to the [Community Events](https://ocaml.org/community).

You can add a new community event by creating a new markdown file in [data/meetups.yml](data/meetups.yml).
You can add a new community event by creating a new Markdown file in [data/meetups.yml](data/meetups.yml).

### <a name="content-package"></a> Add a featured packages
### <a name="content-package"></a> Add a Featured Package

> Contribute to the [Featured Packages](https://ocaml.org/packages).

To update the list of Featured Packages in the Packages page, you can update [data/packages.yml](data/packages.yml)
To update the list of Featured Packages on the Packages page, you can update [data/packages.yml](data/packages.yml)

### <a name="ocaml-changelog"></a> OCaml Changelog

The [OCaml Changelog](https://ocaml.org/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](https://github.com/ocaml/ocaml)
- [The OCaml Platform tools](https://ocaml.org/docs/platform)
- [Ppxlib](https://github.com/ocaml-ppx/ppxlib)
- [OMP](https://github.com/ocaml-ppx/ocaml-migrate-parsetree) (that has been deprecated in favour of Ppxlib)
- [The OCaml Compiler](https://github.com/ocaml/ocaml)
- [OCaml Platform Tools](https://ocaml.org/docs/platform)

Before a release of the above tools land on the opam-repository, the release manager of the project opens a Pull Request on OCaml.org with an announcement for the release.
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 features from 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/`.
To contribute to a new release announcement or feature highlight, add a Markdown file in `data/changelog/`.

## Git and GitHub workflow
## 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](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github).

Feel free to use any approach while creating a pull request. Here are a few suggestions from the dev team:
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 it.
- Clone the repo locally (or continue editing directly in github if the change is small). Checkout
- 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 pull request with a small initial commit. Here's how you can [create a draft pull request.](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
- Continue developing, 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
- Create a draft PR with a small initial commit. Here's how you can [create a draft pull request.](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
- 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.