-
Notifications
You must be signed in to change notification settings - Fork 42
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into hkm/gha-using-devx
- Loading branch information
Showing
99 changed files
with
5,318 additions
and
2,676 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| { | ||
| "image":"ghcr.io/input-output-hk/devx-devcontainer:x86_64-linux.ghc96-iog", | ||
| "onCreateCommand": "on-create-command", | ||
| "customizations":{ | ||
| "vscode":{ | ||
| "extensions":[ | ||
| "haskell.haskell" | ||
| ] | ||
| } | ||
| // Do not set custom `settings` as they would override devx-container defaults... | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| name: Github Pages | ||
|
|
||
| on: | ||
| push: | ||
| branches: [ "master" ] | ||
| workflow_dispatch: | ||
|
|
||
| jobs: | ||
| gh-pages: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| contents: write | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v3 | ||
| - name: Install nix | ||
| uses: cachix/install-nix-action@v20 | ||
| with: | ||
| nix_path: nixpkgs=channel:nixos-unstable | ||
| extra_nix_config: | | ||
| experimental-features = nix-command flakes | ||
| trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= loony-tools:pr9m4BkM/5/eSTZlkQyRt57Jz7OMBxNSUiMC4FkcNfk= | ||
| substituters = https://cache.iog.io https://cache.nixos.org/ https://cache.zw3rk.com | ||
| - name: Build projects and haddocks | ||
| run: nix develop --command bash -c "cabal update && cabal build --enable-documentation all && ./scripts/haddocks.sh" | ||
| - name: Add files | ||
| run: | | ||
| git config --local user.name ${{ github.actor }} | ||
| git config --local user.email "${{ github.actor }}@users.noreply.github.com" | ||
| cp -r ./haddocks/* ./ | ||
| rm -rf haddocks | ||
| git add -A --force | ||
| git commit -m "Updated" | ||
| - name: Push to gh-pages | ||
| uses: ad-m/[email protected] | ||
| with: | ||
| github_token: ${{ secrets.GITHUB_TOKEN }} | ||
| branch: gh-pages | ||
| force: true | ||
| directory: . | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| # Contributing to the Cardano BAse | ||
|
|
||
| ## Roles and responsibilities | ||
|
|
||
| Currently there are two core maintainers: | ||
|
|
||
| * [@lehins](https://github.com/lehins) | ||
| * [@tdammers](https://github.com/tdammers) | ||
|
|
||
| Anything crypto related should be directed at: | ||
|
|
||
| * [@iquerejeta](https://github.com/iquerejeta) | ||
|
|
||
| People who can help with issues regarding this repository's continuous integration and nix | ||
| infrastructure: | ||
|
|
||
| * [@angerman](https://github.com/angerman) | ||
| * [@hamishmack](https://github.com/hamishmack) | ||
|
|
||
| **For security related issues** please consult the security file in the | ||
| [Cardano engineering handbook](https://github.com/input-output-hk/cardano-engineering-handbook/blob/main/SECURITY.md). | ||
|
|
||
| ## Development | ||
|
|
||
| We use trunk based developement. Normal development will branch off of master and be | ||
| merged back to master. | ||
|
|
||
| ### Releasing and versioning | ||
|
|
||
| Packages from `cardano-base` are released to | ||
| [CHaP](https://github.com/input-output-hk/cardano-haskell-packages). | ||
|
|
||
| See documentation on the adopted [release and versioning processes](./RELEASING.md) for | ||
| more information. | ||
|
|
||
| Also see the CHaP README for [instructions](https://github.com/input-output-hk/cardano-haskell-packages#-from-github). | ||
|
|
||
| ## Building | ||
|
|
||
| See the [Readme](https://github.com/input-output-hk/cardano-base#building) for | ||
| instructions on building. | ||
|
|
||
| ## Updating dependencies | ||
|
|
||
| Our Haskell packages come from two package repositories: | ||
| - Hackage | ||
| - [CHaP](https://github.com/input-output-hk/cardano-haskell-packages) (which is | ||
| another alternative Hackage from Cardano) | ||
|
|
||
| The `index-state` of each repository is pinned to a particular time in `cabal.project`. | ||
| This tells Cabal to treat the repository "as if" it was the specified time, ensuring | ||
| reproducibility. If you want to use a package version from repository X which was added | ||
| after the pinned index state time, you need to bump the index state for X. This is not a | ||
| big deal, since all it does is change what packages `cabal` considers to be available when | ||
| solving, but it will change what package versions cabal picks for the plan, and so | ||
| will likely result in significant recompilation, and potentially some breakage. That | ||
| typically just means that we need to fix the breakage (and add a lower-bound on the | ||
| problematic package), or add an upper-bound on the problematic package. | ||
|
|
||
| Note that `cabal` itself keeps track of what index states it knows about, so when you bump | ||
| the pinned index state you may need to call `cabal update` in order for `cabal` to be happy. | ||
|
|
||
| The Nix code which builds our packages also cares about the index state. This is | ||
| represented by inputs managed by `nix flake`: You can update these by running: | ||
| - `nix flake lock --update-input haskellNix/hackage` for Hackage | ||
| - `nix flake lock --update-input CHaP` for CHaP | ||
|
|
||
| If you fail to do this you may get an error like this from Nix: | ||
| ``` | ||
| error: Unknown index-state 2021-08-08T00:00:00Z, the latest index-state I know about is 2021-08-06T00:00:00Z. You may need to update to a newer hackage.nix. | ||
| ``` | ||
|
|
||
| ### Use of `source-repository-package`s | ||
|
|
||
| We *can* use Cabal's `source-repository-package` mechanism to pull in un-released package | ||
| versions. However, we should avoid this. In particular, we cannot release | ||
| our packages to CHaP while we depend on a `source-repository-package`. | ||
|
|
||
| If we are stuck in a situation where we need a long-running fork of a package, we should | ||
| release it to CHaP instead (see the [CHaP | ||
| README](https://github.com/input-output-hk/cardano-haskell-packages) for more). | ||
|
|
||
| If you do add a `source-repository-package`, you need to provide a `--sha256` comment in `cabal.project` so that Nix knows the hash of the content. | ||
|
|
||
| ## Warnings | ||
|
|
||
| While building most compilation warnings will be turned into an error due to | ||
| `-Werror` flag. However during development it might be a bit inconvenient thus | ||
| can be disabled on per project basis: | ||
|
|
||
| ```shell | ||
| cabal configure <package-name> --ghc-options="-Wwarn" | ||
| cabal build <package-name> | ||
| ``` | ||
|
|
||
| ### Additional documentation | ||
|
|
||
| You can find additional documentation on the nix infrastructure used in this | ||
| repo in the following places: | ||
|
|
||
| - [The haskell.nix user guide](https://github.com/input-output-hk/haskell.nix/blob/documentation/docs/user-guide.md) | ||
| - [The nix-tools repository](https://github.com/input-output-hk/nix-tools) | ||
| - [The iohk-nix repository](https://github.com/input-output-hk/iohk-nix) | ||
|
|
||
| Note that the user guide linked above is incomplete and does not correctly refer | ||
| to projects built using `iohk-nix`, as this one is. A certain amount of trial | ||
| and error may be required to make substantive changes! | ||
|
|
||
| ## Working Conventions | ||
|
|
||
| ### Code formatting | ||
|
|
||
| Very soon we will start using [`fourmolu`](https://github.com/fourmolu/fourmolu) for | ||
| formatting, but for now a rule of thumb is to follow whatever format is in a module that | ||
| is being modified. There is a script | ||
| [here](https://github.com/input-output-hk/cardano-base/blob/master/scripts/fourmolize.sh) | ||
| which uses nix to format the appropriate directories. | ||
|
|
||
| ### Compiler warnings | ||
|
|
||
| The CI builds Haskell code with `-Werror`, so will fail if there are any compiler warnings. | ||
|
|
||
| A particular warning can be turned off, if there is a compelling enough reason to do so, | ||
| but it should be done at the module level, rather than for a whole package. | ||
|
|
||
| ### Commit messages | ||
|
|
||
| Summarize changes in around 72 characters or less. | ||
|
|
||
| Provide more detailed explanatory text, if necessary. Wrap it to about 72 characters or | ||
| so. In some contexts, the first line is treated as the subject of the commit and the rest | ||
| of the text as the body. The blank line separating the summary from the body is critical | ||
| (unless you omit the body entirely); various tools like `log`, `shortlog` and `rebase` can | ||
| get confused if you run the two together. | ||
|
|
||
| Explain the problem that this commit is solving, and use one commit per conceptual change. | ||
| Focus on why you are making this change as opposed to how (the code explains that). Are | ||
| there side effects or other unintuitive consequences of this change? Here's the place to | ||
| explain them. | ||
|
|
||
| If you use an issue tracker, put references to them at the bottom, like this: | ||
|
|
||
| Resolves: #123 | ||
| See also: #456, #789 | ||
|
|
||
| ### Commit signing | ||
|
|
||
| Commits are required to be [signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). | ||
|
|
||
| ### Pull Requests | ||
|
|
||
| We require linear history in `master`, so every PR must be rebase on `master` before it | ||
| can be merged. There is a convenience button on a PR "Update branch", but make sure to | ||
| select "Update with Rebase" from the drop down. | ||
|
|
||
| Keep commits to a single logical change where possible. The reviewer will be happier, and | ||
| you’ll be happier if you ever have to revert it. If you can’t do this (say because you | ||
| have a huge mess), best to just have one commit with everything in it. | ||
|
|
||
| Keep your PRs to a single topic. Including unrelated changes makes things harder for your | ||
| reviewers, slowing them down, and makes it harder to integrate new changes. | ||
|
|
||
| If you’re working on something that’s likely to conflict with someone else, talk to | ||
| them. It’s not a race. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.