Welcome to the November and December 2023 edition of the OCaml.org newsletter! This update has been compiled by the OCaml.org team. You can find previous updates on Discuss.
Our goal is to make OCaml.org the best resource for anyone who wants to get started and be productive in OCaml. The OCaml.org newsletter provides an update on our progress towards that goal and an overview of the changes we are working on.
We couldn’t do it without all the amazing OCaml community members who help us review, revise, and create better OCaml documentation. Your feedback enables us to better prioritise our work and make progress towards our goal. Thank you!
This newsletter covers:
- Learn Area: We made substantial changes to the Learn Area UI, introducing a new landing page and improving various elements on the Learn Area’s subpages. Work on a documentation search feature is in progress, and new documentation has been added or substantially improved!
- Upcoming Dark Mode: We completed the UI designs for the upcoming dark mode and our Outreachy intern has started to implement the changes.
- Announcing the Outreachy Interns: We’re happy to welcome two interns to work on OCaml projects!
- General Improvements: As usual, we also worked on general maintenance and improvements based on user feedback, so we’re highlighting some of our work below.
Open Issues for Contributors
We created many issues for external contributors. The majority of them are suitable for OCaml beginners, and we’re happy to review and provide feedback on your pull requests!
You can find open issues for contributors here!
Learn Area
1. Redesign of the Learn Area
OCaml.org is undergoing an exciting transformation, and we’re thrilled to share some key updates with you. Our main focus has been the finalisation and approval of a new user interface (UI) design, aimed at enhancing your experience. This update isn’t just about looks; we’re ensuring the website is fully optimised for mobile and tablet devices.
The collaboration between our team and users like you has been instrumental in shaping the project. Your input and support have been invaluable, and we’re grateful for the community’s involvement in making this website the best it can be.
Our design system has seen several updates, including new components like a variable landing page button, diverse icons (including social media and OCaml icons like Dune and opam), enhanced text styles, updated color variables, and more.
We’ve completed the designs for all pages of the Learn area. Each page has been designed with attention to detail, ensuring consistency and coherence across all versions.
If you’re curious and want to take a closer look at the designs, you can access our Figma Design Files. Please be aware that the content shown on the pages is not always accurate. We aim to provide our designer with better content for the mockups and UI going forward.
The work on implementing the new designs for the light mode of the Learn area have been completed in December!
Relevant PRs and Activities:
- Implemented Learn UI from Figma ocaml/ocaml.org#1798
- @FatumaA contributed: Improve platform page card styles ocaml/ocaml.org#1752
- @florentdrousset contributed: Link exercises to tutorials ocaml/ocaml.org#1753
- Add book links based on Figma design - ocaml/ocaml.org#1834
- WIP: Documentation Search Feature - ocaml/ocaml.org#1871
2. OCaml Documentation
In November, we focussed on addressing and incorporating community feedback on the “Getting Started” documents. The comments and discussion on Discuss were so helpful. We encourage more of that!
We also worked on polishing “Basic Data Types” and “Values and Functions.” Plus the team has been working on new “Modules,” “Functors,” and “Libraries With Dune” documents, hoping to have it, and the ones in community review (below), published before the end of the year.
Relevant PRs and Activities:
- In Progress:
- Sets
- Maps
- Higher Order Functions
- In Review (internal):
- In Review (community):
- Published:
- Running Commands in an opam Switch
- Mutable State / Imperative Programming (see Discuss Thread)
- Announcement on Discuss: New Tutorials on Basics of OCaml
- Basic Data Types (see Discuss Thread)
- Functions and Values (see Discuss Thread)
- Installing OCaml (see Discuss Thread)
- A Tour Of OCaml (see Discuss Thread)
- Your First OCaml Program (see Discuss Thread)
- Introduction to opam Switches
- Fix Homebrew Errors on Apple M1
- Operators
- Error Handling (see Discuss Thread)
- Arrays (see Discuss Thread)
- Sequences (see Discuss Thread)
- Other Activity:
- We integrated pages from OCaml books into the Learn area, reproduced on OCaml.org with permission - ocaml/ocaml.org#1766:
- Compiler & Runtime pages from Real World OCaml, and
- Memoisation & Monads from OCaml Programming: Correct + Efficient + Beautiful
- Rearranged the sections on the Language documentation tab - ocaml/ocaml.org#1756
- Documentation formatting: Replace unsemantic blockquotes by highlighting ocaml/ocaml.org#1759
- We improved the “Is OCaml Web Yet?” page, adding many more packages and reworking the text to more accurately capture the current state of the OCaml web ecosystem - ocaml/ocaml.org#1843
- Editing on Basic Data Types - ocaml/ocaml.org#1827
- Values & Functions :: Addressing suggestions from Issue #1762 - ocaml/ocaml.org#1812
- We integrated pages from OCaml books into the Learn area, reproduced on OCaml.org with permission - ocaml/ocaml.org#1766:
- Contributions:
- @benjamin-thomas improved the
Map
document by providing a better example that uses different types for the key and value ocaml/ocaml.org#1743 - @leostera simplified the “Bootstrapping a Project with Dune” guide - ocaml/ocaml.org#1792
- @FatumaA fixed a typo in “Tour of OCaml” ocaml/ocaml.org#1739
- @binwang-dev contributed: Fix type inconsistency in tutorial ocaml/ocaml.org#1757
- @J3RN contributes: Fix escaping in “Your First OCaml Program” - ocaml/ocaml.org#1846
- @Sc4ramouche contributes: Add comparison of std containers guide to v3 docs - ocaml/ocaml.org#1828
- @Sc4ramouche contributes: Fix typo in Tour of OCaml - ocaml/ocaml.org#1820
- @J3RN contributes: Fix broken “Install Platform Tools” link - ocaml/ocaml.org#1841
- @benjamin-thomas improved the
We started opening issues marked with “help wanted” to enable external contributors to help improve the docs. The response has been overwhelmingly positive, and we’re thrilled to keep this up and make the OCaml documentation truly great with your help!
Upcoming Dark Mode
In December, oyenuga17 started to implement the new dark mode on OCaml.org. Plans are to complete and activate the dark mode based on browser / operating system preferences by early March.
We continuously merge small patches into ocaml.org, and you can take a look at completed dark mode pages on https://staging.ocaml.org. We placed a button at the bottom of the page to toggle the dark mode on staging (this is not going to be released, it is only a means for us to review the dark mode pages).
Relevant Activities and PRs:
- Implement dark mode on learn area landing page - ocaml/ocaml.org#1836
- UI design for dark mode on all OCaml.org pages, and resulting Design System changes
Announcing the Outreachy Interns
In November, we reviewed and rated the Outreachy contributions for the dark mode project and the GUI project and selected the two interns. @oyenuga17 is working with the OCaml.org team on implementing the dark mode, while @IdaraNabuk has been selected for the GUI project. Congratulations @IdaraNabuk and @oyenuga17!
Since the Outreachy application period ended in October, we list all the remaining pull requests done on Outreachy Issues in the “General Improvements” section below.
General Improvements
Most Important Changes TLDR:
- There’s now a self-hosted Plausible.io instance for OCaml.org, accessible at Plausible · ocaml.org!
- You can see the different OCaml teams (Compiler, Platform, Packaging, Infrastructure, OCaml.org) and the maintainers of relevant repositories at the new governance page at Governance!
- The OCaml Logo now has a dedicated page at OCaml Logos!
- We’re now displaying a package’s README on the package overview page.
- You can now list upcoming events with date and time on The OCaml Community.
- OCaml.org now has social media images, so that sharing OCaml.org links looks nicer.
Many thanks go out to the many contributors who helped improve OCaml.org in November and December. Find them listed below!
Relevant PRs and Activities:
- Features / Improvements:
- Added a governance page that lists the maintainers and dev meetings of the compiler, all the projects of the OCaml Platform, and the ocaml.org infrastructure - ocaml/ocaml.org#1239
- @IdaraNabuk contributed: Added the ability to record upcoming events to the community page - ocaml/ocaml.org#1717
- @Girish-Jangam contributed: Added a page for the OCaml logo - ocaml/ocaml.org#1711
- Add ability to disable an OCaml Planet source / fix scraper and scrape missing planet posts - ocaml/ocaml.org#1734
- @leostera contributed: Package search UX improvements - ocaml/ocaml.org#1691
- Added an OpenSearch manifest, so you can add the OCaml packages search to your browser search bar
- Made search input in main navbar gain tab-focus earlier
- Set tabindex=“1” for the in-package search input on the package documentation page
- Autofocus the search inupt on the package search results page
- @mays4 contributed: Add links to CONTRIBUTING.md for all data items that can be contributed - ocaml/ocaml.org#1682
- @m-spitfire contributed: Entries on the changelog page are now paginated - ocaml/ocaml.org#1751
- Add missing social media images to OCaml.org HTML metadata. Now, posts shared on social media have the OCaml logo as image, which is much better than having no image - ocaml/ocaml.org#1784
- We’re now displaying a package’s README on the package overview page. This was part of one of the design options from the package area redesign earlier this year. However, it wasn’t entirely clear that this was the right thing to do. More confirmation came up in terms of people asking for this, so we did it. - ocaml/ocaml.org#1832
- Update to Tailwind CSS 3.3.6 - ocaml/ocaml.org#1850
- Added table of contents to jump to individual sections on “Is OCaml Web yet” - ocaml/ocaml.org#1849
- @RWUBAKWANAYO contributed: Improved responsive layout on releases page - ocaml/ocaml.org#1716
- @kiyov09 contributed: Reduced the number of news items in the blog page to have a similar height to the OCaml Planet column - ocaml/ocaml.org#1754
- @oyenuga17 contributed: Improved responsive collapsing of the table on the papers page - ocaml/ocaml.org#1741
- Bugfixes:
- Adjust CSS order of elements of main nav, starting from 0 - ocaml/ocaml.org#1745
- Set correct background color on learn tabs select element - ocaml/ocaml.org#1746
- @Solar-Rays contributed: Remove links from outreachy project description to prevent overflow - ocaml/ocaml.org#1764
- Patch upstream dependency
river
to fall back to feed entry’sid
iflinks
tag does not exist. This allows more feeds to be scraped successfully. - tarides/river#11 - Added missing Code of Conduct Route - ocaml/ocaml.org#1781
- Added missing ‘Platform Tools’ link in footer - ocaml/ocaml.org#1788
- @AndroGenius-codes contributed: Fixed a bug in pagination where the page number “1” was displayed twice when all the results would fit on a single page - ocaml/ocaml.org#1729
- @Demmythetechie contributed: Add
word-wrap: break-word
to the Tailwind Typography prose class to prevent long URLs in content areas from overflowing - ocaml/ocaml.org#1722 - @AndroGenius-codes contributed: Shorten text on Outreachy Projects link on the community page to prevent overflow - ocaml/ocaml.org#1749
- @oyenuga17 contributed: Render search query as input value on the papers page and the releases page - ocaml/ocaml.org#1747
- @FatumaA contributed: Added spacing below “See All Releases” button on homepage - ocaml/ocaml.org#1740
- @RWUBAKWANAYO contributed: Resolve text styling issue in release list headers ocaml/ocaml.org#1773
- @kevanantha contributed: Fix invalid link for exercises ocaml/ocaml.org#1802
- Other:
- @oyenuga17 contributed: Replaced dependency
omd
withcmarkit
- ocaml/ocaml.org#1642. Thanks for this excellent and challenging contribution! - Remove Yoshi tool - ocaml/ocaml.org#1735
- Removed dream-dashboard, it was replaced a self-hosted plausible.io instance - ocaml/ocaml.org#1736
- Rename Tutorials->Documentation in meta title of Learn Area - ocaml/ocaml.org#1789
- @oyenuga17 contributed: Replaced dependency
- Content:
- Added “Introduction to Functional Programming and the Structure of Programming Languages using OCaml” to the books section - ocaml/ocaml.org#1744
- Added the changelog for opam.2.2.0~alpha3 - ocaml/ocaml.org#1771
- Update title of Platform Roadmap document to ‘OCaml Platform Roadmap’ - ocaml/ocaml.org#1790
- Add some feeds to the OCaml Planet - ocaml/ocaml.org#1779
- Added “Practical OCaml” blog to the Planet - ocaml/ocaml.org#1806
- @caisar-platform contributed: Fix broken link in CEA Research Engineer offer. ocaml/ocaml.org#1787
- @KihongHeo contributed: Add KAIST as an academic institution ocaml/ocaml.org#1791
- @hetzenmat contributes: Fix wrong release date for 5.1.1 - ocaml/ocaml.org#1858
- @zapashcanon contributes: Fix order of presentations - ocaml/ocaml.org#1859
- @oyenuga17 contributes: add outreachy blog | introduce yourself - ocaml/ocaml.org#1848
- @IdaraNabuk contributed: Add Outreachy Blog Post to OCaml Planet ocaml/ocaml.org#1878
- Added ‘Retrofitting Parallelism onto OCaml’ paper - ocaml/ocaml.org#1875