diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..ca27d661 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,7 @@ +## Description + + + +## Checklist + +- [ ] Titles and headings use [AP Title Case](https://titlecaseconverter.com/) (see [Style Guide](../CONTRIBUTING.md#style-guide)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e805f2f..ca9a1874 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,43 +1,132 @@ # Contributors Guide +## Table Of Contents + +- [Bug Reports](#bug-reports) +- [Documentation](#documentation) +- [Style Guide](#style-guide) +- [Code](#code) +- [Building the site](#building-the-site) +- [Styling (CSS / Tailwind)](#styling-css--tailwind) +- [CI](#ci) +- [Code Quality](#code-quality) + ## Bug Reports Please [open an issue](https://github.com/haskellfoundation/haskellfoundation.github.io/issues/new) if you have a bug to report. -The more detailed your report, the faster it can be resolved and will ensure it -is resolved in the right way. I personally appreciate it when people not only open -issues, but attempt to resolve them on their own by submitting a pull request. I am -always open to constructive feedback, and I am by no means an expert, so guidance -should always be considered welcome. +The more detailed your report, the faster it can be resolved and will ensure it is resolved in the right way. We appreciate when people not only open issues, but attempt to resolve them on their own by submitting a pull request. We are always open to constructive feedback. ## Documentation -If you would like to help with documentation, please remember to update any and -all module headers with the appropriate copyright dates, ranges, and authorship. - Expansions to the documentation are welcome, and appreciated. Every contribution counts. +## Style Guide + +We seek to adhere to the [SIGPLAN Proceedings Format](https://www.sigplan.org/Resources/ProceedingsFormat/). + +### Titles and headings + +Titles (page titles, news/blog post titles, etc.) and headings (e.g., section headings) should use [AP Title Case](https://titlecaseconverter.com/rules/#AP): + +- Capitalize the first word and the last word of the title +- Capitalize the principal words +- Capitalize to in infinitives +- Capitalize all words of four letters or more +- Do not capitalize articles, conjunctions, and prepositions of three letters or fewer + +Example: "How the Haskell Foundation Works With Affiliates". + +When in doubt, run the title through the [Title Case Converter](https://titlecaseconverter.com/) with the "AP" style selected. + ## Code -If you would like to contribute code to fix a bug, add a new feature, or -otherwise improve this site, pull requests are most welcome. It's a good idea to -[submit an issue](https://github.com/haskellfoundation/haskellfoundation.github.io/issues/new) to -discuss the change before plowing into writing code. +If you would like to contribute code to fix a bug, add a new feature, or otherwise improve this site, pull requests are most welcome. It's a good idea to [submit an issue](https://github.com/haskellfoundation/haskellfoundation.github.io/issues/new) to discuss the change before plowing into writing code. + +> **Note:** Development happens on the `hakyll` branch. The `main` branch holds only the built site and is overwritten by CI. + +## Building the site + +The site can be built with either [Stack](https://docs.haskellstack.org) or [Cabal](https://www.haskell.org/cabal/) — use whichever you prefer. + +To build the project: + +```bash +stack build # with Stack +cabal build # with Cabal +``` + +Once the project has built (which can take a while due to the dependencies for Hakyll), generate the site with: + +```bash +stack exec -- site build # with Stack +cabal run site -- build # with Cabal +``` + +and for development (a server that rebuilds on change): + +```bash +stack exec -- site watch # with Stack +cabal run site -- watch # with Cabal +``` + +The site will be built in the `_site` directory, and you can open the files in your browser of choice. Due to a Hakyll issue, some sponsor logos will not show up correctly. This is expected behavior, and should be fine for the deployed site. + +## Styling (CSS / Tailwind) + +The site is styled with [Tailwind CSS](https://tailwindcss.com) (v4). Tailwind is a CSS framework whose classes are short abbreviations for inline styles (e.g. `pt-4`, `text-center`), scattered directly across the HTML templates and content. At build time the Tailwind compiler acts as a kind of "CSS tree-shaker": it scans the site for the Tailwind classes actually in use and emits only the CSS needed for them. + +Two files matter: + +- `assets/css/tailwind.css` — the Tailwind entry point. It holds the v4 CSS-native configuration (`@theme` colors/fonts, `@plugin`, and the `@source` lines that tell the compiler which directories to scan). **New pages that use Tailwind classes must add an `@source` line here**, or those classes will be dropped from the production build. +- `assets/css/main.css` — hand-written CSS that is *not* processed by Tailwind. This is the place for ordinary, non-Tailwind styles. + +### Do I need Node installed? + +**No, if you are only editing content or Haskell code.** Hakyll concatenates a checked-in snapshot, `dev.css`, onto `assets/css/tailwind.css` at build time (see the `match "assets/css/tailwind.css"` rule in `site.hs`). `dev.css` is a pre-generated copy of the real Tailwind output, so `stack exec -- site build` on its own produces a site that looks close enough to preview — no Node toolchain required. This keeps the site accessible to contributors of all skill sets. + +**Yes, if you are changing the appearance.** Because `dev.css` is only a snapshot, it does *not* reflect edits to `assets/css/tailwind.css`, `assets/css/main.css`, `tools/tailwind/postcss.config.js`, or any *newly used* Tailwind class. To regenerate the real CSS you need [Node.js](https://nodejs.org). The Node/Tailwind toolchain lives in [`tools/tailwind/`](tools/tailwind/) (see its README), separate from the Hakyll project, so run npm from there: + +```bash +cd tools/tailwind +npm ci # once, to install the toolchain +npm run build # compile -> _site/assets/css/tailwind.css +npm run build:production # minified build (NODE_ENV=production) +``` + +If you do not want to install `npm` globally and have `nix` available, drop into the Nix development shell which provides `npm` and a basic Haskell toolchain. + +If your change alters the CSS, regenerate the checked-in `dev.css` snapshot and commit it: + +```bash +cd tools/tailwind +npm run build:dev-snapshot # recompile the dev.css snapshot in place +``` + +CI runs this same command and fails the build if the committed `dev.css` is out of date, so a stale snapshot cannot slip through review. + +> **Note:** `dev.css` is only an *unminified* snapshot of `npm run build`; it still differs from the minified `npm run build:production` output shipped to production, so verify appearance-critical changes against a real production build. + +## CI + +We use GitHub Actions `.github/workflows/main.yml` to build the site for production. -If relevant, any and all claims of "performance" should be backed up with benchmarks. You can -add them to the existing benchmark suite in your PR, as long as you do not make -unjustifiable changes to the existing code. +The general steps are: -### Building the site +1. Check out the `hakyll` branch +2. Install Haskell and Node.js +3. Restore the cached build artefacts +4. Build the `site` executable +5. Rebuild the site contents using the `site` executable +6. Build the production CSS (`cd tools/tailwind && npm ci && npm run build:production`) +7. Check out the `main` branch +8. Copy the `_site` directory over the `main` branch contents +9. Commit and push the site contents to the `main` branch. -Refer to the [README](README.md) for more information on building the site. +Steps 7–9 (the deploy) run only on non-PR pushes to `hakyll`; pull requests build and stop after step 6. ## Code Quality -The `haskell.foundation` project intends to focus on integration and usability, -balanced with maintainability. +The `haskell.foundation` website intends to focus on integration and usability, balanced with maintainability. -We strive to be an example of best practices for real Haskell. If you believe -there is a better way to do something in the code, please let us know or -submit a PR for review. We would like the HF website to be a clear example of -how to do a Hakyll website right. +We strive to be an example of best practices for real Haskell. If you believe there is a better way to do something in the code, please let us know or submit a PR for review. We would like the HF website to be a clear example of how to do a Hakyll website right. diff --git a/README.md b/README.md index 13e16638..290cd348 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,12 @@

-Haskell Foundation +Haskell Foundation

# The Haskell Foundation Website [![Hackage](https://img.shields.io/static/v1?label=Haskell%20Foundation&message=official&color=purple&style=for-the-badge)](https://haskell.foundation) -This repository is for the [haskell.foundation](https://haskell.foundation) website. It is a proud, Hakyll-based site, built as an in-kind contribution from [Obsidian Systems](https://obsidian.systems), and maintained by the Haskell Foundation and its volunteers. If you would like to get started with a merge request, please consult the documentation below. - -## Table Of Contents - -- [The Haskell Foundation Website](#the-haskell-foundation-website) - - [Table Of Contents](#table-of-contents) - - [Building](#building) - - [Styling (CSS / Tailwind)](#styling-css--tailwind) - - [CI](#ci) - - [License](#license) - -## Building - -The site can be built with either [Stack](https://docs.haskellstack.org) or -[Cabal](https://www.haskell.org/cabal/) — use whichever you prefer. - -To build the project: - -```bash -stack build # with Stack -cabal build # with Cabal -``` - -Once the project has built (which can take a while due to the dependencies for Hakyll), generate the site with: - -```bash -stack exec -- site build # with Stack -cabal run site -- build # with Cabal -``` - -and for development (a server that rebuilds on change): - -```bash -stack exec -- site watch # with Stack -cabal run site -- watch # with Cabal -``` - -The site will be built in the `_site` directory, and you can open the files in your browser of choice. Due to a Hakyll issue, some sponsor logos will not show up correctly. This is expected behavior, and should be fine for the deployed site. - -For further information, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) at the root of this project. - -## Styling (CSS / Tailwind) - -The site is styled with [Tailwind CSS](https://tailwindcss.com) (v4). Tailwind is a CSS framework whose classes are short abbreviations for inline styles (e.g. `pt-4`, `text-center`), scattered directly across the HTML templates and content. At build time the Tailwind compiler acts as a kind of "CSS tree-shaker": it scans the site for the Tailwind classes actually in use and emits only the CSS needed for them. - -Two files matter: - -- `assets/css/tailwind.css` — the Tailwind entry point. It holds the v4 CSS-native configuration (`@theme` colors/fonts, `@plugin`, and the `@source` lines that tell the compiler which directories to scan). **New pages that use Tailwind classes must add an `@source` line here**, or those classes will be dropped from the production build. -- `assets/css/main.css` — hand-written CSS that is *not* processed by Tailwind. This is the place for ordinary, non-Tailwind styles. - -### Do I need Node installed? - -**No, if you are only editing content or Haskell code.** Hakyll concatenates a checked-in snapshot, `dev.css`, onto `assets/css/tailwind.css` at build time (see the `match "assets/css/tailwind.css"` rule in `site.hs`). `dev.css` is a pre-generated copy of the real Tailwind output, so `stack exec -- site build` on its own produces a site that looks close enough to preview — no Node toolchain required. This keeps the site accessible to contributors of all skill sets. - -**Yes, if you are changing the appearance.** Because `dev.css` is only a snapshot, it does *not* reflect edits to `assets/css/tailwind.css`, `assets/css/main.css`, `tools/tailwind/postcss.config.js`, or any *newly used* Tailwind class. To regenerate the real CSS you need [Node.js](https://nodejs.org). The Node/Tailwind toolchain lives in [`tools/tailwind/`](tools/tailwind/) (see its README), separate from the Hakyll project, so run npm from there: - -```bash -cd tools/tailwind -npm ci # once, to install the toolchain -npm run build # compile -> _site/assets/css/tailwind.css -npm run build:production # minified build (NODE_ENV=production) -``` - -If you do not want to install `npm` globally and have `nix` available, drop into -the Nix development shell which provides `npm` and a basic Haskell toolchain. - -If your change alters the CSS, regenerate the checked-in `dev.css` snapshot and -commit it: - -```bash -cd tools/tailwind -npm run build:dev-snapshot # recompile the dev.css snapshot in place -``` - -CI runs this same command and fails the build if the committed `dev.css` is out -of date, so a stale snapshot cannot slip through review. - -> **Note:** `dev.css` is only an *unminified* snapshot of `npm run build`; it still differs from the minified `npm run build:production` output shipped to production, so verify appearance-critical changes against a real production build. - -## CI - -We use GitHub Actions `.github/workflows/main.yml` to build the site for production. - -The general steps are: - -1. Check out the `hakyll` branch -2. Install Haskell and Node.js -3. Restore the cached build artefacts -4. Build the `site` executable -5. Rebuild the site contents using the `site` executable -6. Build the production CSS (`cd tools/tailwind && npm ci && npm run build:production`) -7. Check out the `main` branch -8. Copy the `_site` directory over the `main` branch contents -9. Commit and push the site contents to the `main` branch. - -Steps 7–9 (the deploy) run only on non-PR pushes to `hakyll`; pull requests build and stop after step 6. +This repository is for the [haskell.foundation](https://haskell.foundation) website. It is a proud, Hakyll-based site, originally built as an in-kind contribution from [Obsidian Systems](https://obsidian.systems), and maintained by the Haskell Foundation and its volunteers. If you would like to get started with a merge request, please consult [CONTRIBUTING.md](CONTRIBUTING.md). ## License diff --git a/board-nominations/index.html b/board-nominations/index.html index dc14feb0..cc99d469 100644 --- a/board-nominations/index.html +++ b/board-nominations/index.html @@ -5,7 +5,7 @@
$partial("templates/corners.html")$
-

Haskell Foundation Board Call For Nominations

+

Haskell Foundation Board Call for Nominations

@@ -17,7 +17,7 @@

Haske

The Haskell Foundation is a new non-profit organisation that seeks to articulate the benefits of functional programming to a broader audience, to erase barriers to entry, and to support Haskell as a solidly reliable basis for mission-critical applications.

The Foundation Board

-

Remit Of The Board

+

Remit of the Board

The Board provides the strategic leadership for the Foundation, and is the decision-making body for everything the Foundation does. More specifically

-

Guidelines For Respectful Communication

+

Guidelines for Respectful Communication

As members of the Haskell Foundation, we commit ourselves to a high standard of public behaviour. We have one over-arching rule:

We strive to treat every person with respect.

diff --git a/news/2020-11-05/haskell-foundation-board-of-directors-call-for-nominations.markdown b/news/2020-11-05/haskell-foundation-board-of-directors-call-for-nominations.markdown index 2735943a..1cb7c1b8 100644 --- a/news/2020-11-05/haskell-foundation-board-of-directors-call-for-nominations.markdown +++ b/news/2020-11-05/haskell-foundation-board-of-directors-call-for-nominations.markdown @@ -1,5 +1,5 @@ --- -title: Haskell Foundation Board Of Directors Call For Nominations +title: Haskell Foundation Board of Directors Call for Nominations --- The Haskell Foundation has issued a call for nominations to the Board of Directors. Nominations will remain open until January 11, 2021. New Board members will be selected by the interim members of the Board of Directors. diff --git a/news/2023-09-21/ghc-api-stability-initiative.markdown b/news/2023-09-21/ghc-api-stability-initiative.markdown index 9ba7f599..f0542ab6 100644 --- a/news/2023-09-21/ghc-api-stability-initiative.markdown +++ b/news/2023-09-21/ghc-api-stability-initiative.markdown @@ -1,5 +1,5 @@ --- -title: Charting a course toward a stable API for GHC +title: Charting a Course Toward a Stable API for GHC link: https://discourse.haskell.org/t/charting-a-course-toward-a-stable-api-for-ghc/7646 --- diff --git a/resources/guidelines-for-respectull-communication.markdown b/resources/guidelines-for-respectull-communication.markdown index 7466b905..15ee24ad 100644 --- a/resources/guidelines-for-respectull-communication.markdown +++ b/resources/guidelines-for-respectull-communication.markdown @@ -1,5 +1,5 @@ --- -title: Guidelines For Respectful Communication +title: Guidelines for Respectful Communication link: /guidelines-for-respectful-communication link-text: Guidelines for Respectful Communication --- diff --git a/resources/more-on-affiliation.markdown b/resources/more-on-affiliation.markdown index 004cc3be..422998fd 100644 --- a/resources/more-on-affiliation.markdown +++ b/resources/more-on-affiliation.markdown @@ -1,5 +1,5 @@ --- -title: More On Affiliation +title: More on Affiliation link: /affiliates link-text: HF Affiliates --- diff --git a/templates/donations/list.html b/templates/donations/list.html index 4fc8a64f..c4a2be27 100644 --- a/templates/donations/list.html +++ b/templates/donations/list.html @@ -10,7 +10,7 @@

Donations

-

Donating To The Haskell Foundation

+

Donating to the Haskell Foundation

Individuals can donate to the Haskell Foundation and help us drive broader adoption of the Haskell language. Click the button to donate through Donorbox! diff --git a/templates/homepage.html b/templates/homepage.html index 10ffefd3..dcfd6daa 100644 --- a/templates/homepage.html +++ b/templates/homepage.html @@ -123,7 +123,7 @@

Empowering the community.

Openness, friendliness, and diversity.

-

For many, Haskell is more a way of life than a programming language. All are welcome, all can contribute. To this end we have adopted the Haskell Guidelines For Respectful Communication.

+

For many, Haskell is more a way of life than a programming language. All are welcome, all can contribute. To this end we have adopted the Haskell Guidelines for Respectful Communication.

diff --git a/vision/index.html b/vision/index.html index 7834a535..faa8e684 100644 --- a/vision/index.html +++ b/vision/index.html @@ -69,7 +69,7 @@

Principles and Ethos

-

Organization

+

Organization

The Haskell community comprises an amazing group of technical talent, and functions today as an almost entirely volunteer effort. The Haskell Foundation will not change that. Our goal is to make every member of the Haskell community, and every Haskell committee, feel more supported, and more productive. We want to enlarge and diversify our community going forward. Here’s a picture:
@@ -121,12 +121,12 @@

Improving the Haskell Adoption Story

A principal goal of the Foundation is to promote adoption of Haskell. We see that task as having three major components:

-

Eliminating unreasonable barriers to adoption

+

Eliminating Unreasonable Barriers to Adoption

We expect that with HF adding a little structure, some things can be improved immediately. For example, we need an entry point for Haskell that speaks to the needs of a range of users: from engineers looking for an easy on-ramp with our best advice on how to learn and use Haskell, to team leaders who want to assess Haskell adoption as a business decision. The Haskell community today does not cover the full range of content needed to promote adoption. This is one example where an organization with the right focus and some resources can easily have a positive impact.

-

Educating the tech community

+

Educating the Tech Community

Engineers are typically the ones who drive Haskell adoption. But they often need permission or sponsorship from managers 1 or 2 levels higher. These decision makers are people who are more concerned about speed of development, reliability, maintenance, and people. We need to explicitly address a broader audience and position Haskell as the best solution to many problems, while maintaining integrity and avoiding too much “marketing speak".

@@ -142,7 +142,7 @@

Educating the tech community

Beyond that, the pesky problem of the marketplace for Haskellers remains. We often hear about fear of hiring bottlenecks and we know some engineering leaders that list this as the number one concern about Haskell. These leaders need to know one thing. You don’t have to hire a Haskell team: Haskell can make your team. Your smart Python developers can learn how to make reliable software and will love you for letting them. There is a role for HF to bridge the gap between the countless developers who want to learn and write Haskell, and the decision makers who currently believe it is hard to find these people.

-

Technical Agenda: Enhancing the tooling, filling the gaps

+

Technical Agenda: Enhancing the Tooling, Filling the Gaps

Haskell Foundation will identify a list of technical goals that will ease adoption and improve Haskell use in production. We have established an initial agenda and are seeking to refine it as we go forward. As HF evolves, we will engage technical discussion in a transparent way, with input from the community.

diff --git a/whitepaper/index.html b/whitepaper/index.html index 15684d66..1bf8ba76 100644 --- a/whitepaper/index.html +++ b/whitepaper/index.html @@ -4,7 +4,7 @@
$partial("templates/corners.html")$
-

A New Chapter For Haskell: The Haskell Foundation

+

A New Chapter for Haskell: The Haskell Foundation

@@ -29,7 +29,7 @@

Goals

  • To identify and fill missing “technical gaps”: the useful stuff that makes for a smooth user experience (pain-free installers, documentation, error messages, and much more).
  • To help with “community glue”, by nurturing respectful, inclusive communication across the community. Together these goals form the mission of HF.
  • -

    Principles And Ethos

    +

    Principles and Ethos

    How ​ we pursue the goals of HF is just as important as ​ what the goals are. HF’s actions will be guided by these core principles:

      @@ -41,7 +41,7 @@

      Principles And Ethos

    We have learned from other open source communities. The ​Rust community​ has a code of conduct that has benefited the community. They do a remarkably good job of this, in large part because the Rust community is actively led and nurtured. ​ The Apache Software Foundation​ has developed clear standards of transparency and consistent governance across all of its 300+ projects, run by volunteers. As we set up HF we have adopted successful approaches like these into our operating principles.

    -

    Organization And Funding

    +

    Organization and Funding

    The organization will seek funding to ensure the longevity and continuous strengthening of the Haskell ecosystem.

    STRUCTURE

    @@ -68,7 +68,7 @@

    WHO ARE THE HF ORGANIZERS?

    FUNDING

    There have been other initiatives of this kind in the past, but they have proved hard to sustain. A big part of this has been a simple lack of bandwidth in a highly decentralised community run entirely by volunteers. We expect to launch with a small group of founding sponsors. The Board and staff will take over that function after launch. Our goal is to raise around $$1m/year in cash and in-kind contributions.

    -

    Improving The Haskell Adoption Story

    +

    Improving the Haskell Adoption Story

    Promoting Haskell adoption has three major components:

      @@ -76,10 +76,10 @@

      Improving The Haskell Adoption Story

    • Educating the tech community about the benefits of adoption, including decision makers.
    • Enhancing the tooling, so that the risk of adoption is dramatically reduced.
    -

    Eliminating Unreasonable And Perceived Barriers To Adoption

    +

    Eliminating Unreasonable and Perceived Barriers to Adoption

    We expect that with HF adding a little structure, some things can be improved immediately. For example, we need an entry point for Haskell that speaks to the needs of a range of users: from engineers looking for an easy on-ramp with our best advice on how to learn and use Haskell, to team leaders who want to assess Haskell adoption as a business decision. The Haskell community today does not cover the full range of content needed to promote adoption. This is one example where an organization with the right focus and some resources can easily have a positive impact.

    -

    Educating The Tech Community

    +

    Educating the Tech Community

    Engineers are typically the ones who drive Haskell adoption. But they often need permission or sponsorship from managers 1 or 2 levels higher. These decision makers are people who are more concerned about speed of development, reliability, maintenance, and people. We need to explicitly address a broader audience and position Haskell as the best solution to many problems, while maintaining integrity and avoiding too much “marketing speak".

    Conditions for telling this story are favorable. The days of a senior sysadmin dictating which version of Java or Python “shall be used” are dying. Containers and cloud technology have inadvertently conspired to permit engineering teams to make these decisions more often at a team level, even in larger organizations. Still, these teams need air cover and solid tools so that their decisions don’t look “rogue” to the rest of the organization.

    @@ -90,7 +90,7 @@

    Educating The Tech Community

    Beyond that, the pesky problem of the marketplace for Haskellers remains. We often hear about fear of hiring bottlenecks and we know some engineering leaders that list this as the number one concern about Haskell. These leaders need to know one thing. You don’t have to hire a Haskell team: Haskell can make your team. Your smart Python developers can learn how to make reliable software and will love you for letting them. There is a role for HF to bridge the gap between the countless developers who want to learn and write Haskell, and the decision makers who currently believe it is hard to find these people.

    -

    Technical Agenda: Enhancing The Tooling, Filling The Gaps

    +

    Technical Agenda: Enhancing the Tooling, Filling the Gaps

    Haskell Foundation will identify a list of technical goals that will ease adoption and improve Haskell use in production. We have established an initial agenda and are seeking to refine it as we go forward. As HF evolves, we will engage technical discussion in a transparent way, with input from the community.