Code restructuring & open-source readiness

.gitignore

@@ -5,3 +5,5 @@ report/leios-design.pdf
 report/leios-design.toc
 *~
 dist-newstyle/
+\#*
+.\#*

CODE-OF-CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at {{ email }}. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

CODING-STANDARDS.md

@@ -0,0 +1,46 @@
+# Coding Standards
+
+This document provides rules, guidelines, and advices on the structure
+of submitted code. As we expect this repository to host code in
+various languages, this document will be expanded as needed and we
+might link to other relevant documents.
+
+## Haskell
+
+### Code formatting
+
+* Haskell code must be formatted using [fourmolu](https://fourmolu.github.io/) tool, using [provided](fourmolu.yaml) configuration file.
+* Cabal files must be formatted using [cabal-fmt](https://github.com/phadej/cabal-fmt).
+
+Check both tools' documentation on how to set it up in your particular environment.
+
+### Testing
+
+We use [hspec](https://hspec.github.io) for writing tests, and we
+favour [QuickCheck](https://hackage.haskell.org/package/QuickCheck)
+tests over unit tests. All submitted code should be accompanied with
+some tests.
+
+## Git
+
+### Commit message format
+
+Here are [seven rules](https://cbea.ms/git-commit/) for great git commit messages:
+
+* Separate subject from body with a blank line
+* Limit the subject line to 50 characters (soft limit)
+* Capitalize the subject line
+* Do not end the subject line with a period
+* Use the imperative mood in the subject line and suffix with ticket number if applicable
+* Wrap the body at 72 characters (hard limit)
+* Use the body to explain what and why vs. how
+
+> [!TIP]
+> Git commit messages are our only source of why something was changed the way it was changed. So we better make the readable, concise and detailed (when required).
+
+### Squash & Rebase PRs
+
+When merging accepted Pull Requests, use `Squash & Merge` and ensure the branch has been rebased on top of `main`.
+
+> [!TIP]
+> Individual commits history of PRs are mostly useless, and PRs should be small and self-contained.

CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing to Leios
+
+Thanks for considering contributing and help us on prototyping and
+specifying the Mithril protocol for the whole benefit of the Cardano
+community!
+
+There are several ways in which you can contribute to this project:
+
+* From reading the [research
+  paper](https://iohk.io/en/research/library/papers/high-throughput-blockchain-consensus-under-realistic-network-assumptions/),
+  identify questions that will need to be answered for a practical
+  implementation of the protocol
+* Analyse and document the protocol, its performance profile,
+  resources requirements, etc.
+* Contribute code for prototypes, simulations, numerical analysis, graphing...
+* Use the provided prototypes and simulations and provide feedback
+
+## Communication channels
+
+Should you have any questions or need some help in getting set up, you can use
+these communication channels to reach the Leios R&D community and get answers in a way
+where others can benefit from it as well:
+
+- #leios on the IOG [Discord server]https://discord.gg/Bc6ABMS3)
+- GitHub [Discussions](https://github.com/input-output-hk/ouroboros-leios/discussions)
+
+## Your first contribution
+
+Contributing to the documentation, its translation, reporting bugs or proposing features are awesome ways to get started.
+
+### Documentation
+
+We host our documentation / user manual as a website [here](https://leios.cardano-scaling.org/).
+
+Each page has an "Edit this page" button which should take you to the source
+file containing the markup. Should you would want to extend the documentation or
+find some errors, please file an issue pointing to the mistake or even better,
+create a pull request with the changes directly!
+
+### Issues
+
+Whether you found a bug in some code in this repository, or have a specific request to improve it, please [submit an issue](https://github.com/input-output-hk/ouroboros-leios/issues/new).
+
+For bug reports, it's very important to explain
+
+- what version you used (typically a commit SHA or a released version number),
+- steps to reproduce (or steps you took),
+- what behavior you saw (ideally supported by logs), and
+- what behavior you expected.
+
+### Feature ideas
+
+For ideas and questions that need some discussions, we use the [Ideas
+discussions
+category](https://github.com/input-output-hk/ouroboros-leios/discussions/)
+to discuss. Please note that we expect all participants to those
+discussions to be mindful of and respect our [Code of
+Conduct](CODE-OF-CONDUCT.md).
+
+## Making changes
+
+When contributing code, it helps to have discussed the rationale and (ideally)
+how something is implemented in a feature idea or bug ticket beforehand.
+
+### Building & Testing
+
+#### Haskell
+
+To build Haskell code in this repository, you need to install:
+
+* The [GHC](https://www.haskell.org/ghc/) compiler version 9.6.3
+* [cabal](https://www.haskell.org/cabal/) build tool
+
+> [!NOTE]
+> Installing those tools might depend on your system's details, we suggest two different methods:
+>
+> * Install [GHCup](https://www.haskell.org/ghcup/) to manage various tools from the Haskell ecosystem
+> * Use the provided [Nix shell](shell.nix)
+
+Running `cabal update && cabal build all` at the top-level of the
+project should build all the Haskell components. Tests are run with
+`cabal test all`.
+
+Besides these general build instructions, some components might document
+additional steps and useful tools in their `README.md` files.
+
+### Coding standards
+
+Make sure to read and follow our [Coding
+Standards](CODING-STANDARDS.md), it includes guidelines on code
+formatting, general style, and some processes. To propose new
+standards or changes to the existing standards, file an issue.
+
+### Creating a pull request
+
+Thank you for contributing your changes by opening a pull requests! To get
+something merged we usually require:
+
+- Description of the changes - if your commit messages are great, this is less important
+- Quality of changes is ensured - through new or updated automated tests in [GitHub Actions](https://github.com/input-output-hk/ouroboros-leios/actions)
+- Change is related to an issue, feature (idea) or bug report - ideally discussed beforehand
+- Well-scoped - we prefer multiple PRs, rather than a big one
+- All your commits must be [signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) in order to be merged in the `main` branch
+
+### Versioning & Changelog
+
+TBD
+
+### Releasing
+
+TBD

README.md

@@ -1,11 +1,38 @@
-This repository is for documentation and tools related to the design and prototyping of Ouroboros Leios.
+This repository is home of the _Leios R&D project_ whose purpose is to define a specification of the Ouroboros Leios protocol.
+
+> [!DANGER]
+> This project is in its very early stage and is mostly
+> experimental and exploratory. All contributions and feedbacks are
+> welcome. No warranties of any kind about the current or future
+> features of Cardano are to be expected, implicitly and explicitly.
+
+# Getting started
+
+Checkout [CONTRIBUTING.md](CONTRIBUTING.md) document for possible contributions and communication channels
+
+More documentation about Leios can be found in various sources:
+
+* The [Leios CIP](https://github.com/cardano-foundation/CIPs/pull/379) providing rationale and high-level design of the protocol
+* The original [Research paper](https://iohk.io/en/research/library/papers/high-throughput-blockchain-consensus-under-realistic-network-assumptions/) is of course the _north star_ of this project
+* One of the paper's co-author, Giorgos Panagiotakos, has shot a [video](https://www.youtube.com/watch?v=YEcYVygdhzU) explaining Leios
+* [These slides ](https://docs.google.com/presentation/d/1W_KHdvdLNDEStE99D7Af2SRiTqZNnVLQiEPqRHJySqI/edit?usp=sharing) from Sandro Coretti-Drayton, another researcher that worked on Leios might also help getting a good intuition about Leios
 
 # Content
 
-The [Leios CIP](https://github.com/cardano-foundation/CIPs/pull/379) initially proposed in November 2022, yielded the following content:
+## Project progress
+
+The [Logbook](Logbook.md) contains a detailed account of problems,
+successes, failures, ideas, references and is intended as a tool to
+help the team members stay in sync. It's updated frequently with notes
+about the day-to-day work, meetings, ideas, etc.
+
+## Archive
+
+The [Leios CIP](https://github.com/cardano-foundation/CIPs/pull/379)
+initially proposed in November 2022, yielded the following
+content. While the material there is still relevant and useful, it
+won't be updated in the future.
 
 * `report`: the LaTeX source for the design report
 * `CIP`: the initial version of the Leios CIP
 * `simulation`: simulation and visualisation code for investigating Leios-like network traffic patterns.
-
-The [Logbook](Logbook.md) contains a detailed account of problems,  successes, failures, ideas, references and is intended as a tool to  help the team members stay in sync.