Doc, Update Readme

Update Readme file with links to contribution and licensing and branch policy

README.adoc

@@ -1,29 +1,102 @@
-# Marconi 
+= https://github.com/input-output-hk/marconi[Cardano Blockchain Indexer Framework]
+:email: plutus@iohk.io
+:author: Input Output HK Limited
+:toc: left
+:reproducible:
+
+image:https://img.shields.io/badge/policy-Cardano%20Engineering%20Handbook-informational[link=https://input-output-hk.github.io/cardano-engineering-handbook]
 
 ## Introduction
 
 Marconi is A lightweight customizable solution for indexing and querying the Cardano blockchain.
 
-### Built by IOG in Haskell
-The purpose of Marconi is ....
+This repository contains:
+
+- link:./marconi-core[marconi-core]
+- link:./marconi-chain-index[marconi-chain-indexer]
+- link:./marconi-sidechain[marconi-sidechain]
+
+[IMPORTANT]
+====
+The rest of this README is focussed on people who want to develop or contribute to the Framework.
+
+====
+
+== Development
+
+[[how-to-develop]]
+=== How to develop and contribute to the project
+
+Run `nix develop` to enter the development shell and you will be presented with a list of available commands.
+
+**Please see link:CONTRIBUTING{outfilesuffix}[CONTRIBUTING] for comprehensive documentation on how to contribute to the project, including development and submitting changes*
+
+== Documentation
+
+=== User documentation
+
+User documentations are work in progress. You may generate Haskell API documenations (haddocks) directly from the `nix shell` for each of marconi compoments:
+
+```
+cabal new-haddock marconi-core
+cabal new-haddock marconi-chain-index
+cabal new-haddock marconi-sidechain
+
+```
+
+== Branching, Versioning and Releases
+
+At this time our protected branch is `main`.
+We adopt the PVP versioning scheme.
+Check out link:doc/BRANCHING-AND-RELEASE.adoc[Branching Policy and Release Process] to learn more.
+
+=== Dependency update
+
+The dependency update policy is dependent on the protected branch.
+
+For `cardano-node`, we define major-version-bound the range of versions which are compatible with a specific era.
+For example, for the Alonzo era, that would be `>= 1.29 && < 1.35`. For the Vasil era, that would be `>= 1.35 && < 1.36`.
+
+Independently of the protected branch:
+
+* It should always use the same first-major-version of `plutus` as the one used by the `plutus` dependency of `cardano-node`
+* It should always be safe to upgrade to a new second-major-version of `plutus`: at worst this will lead to some code breakage.
+* It should, unless specified otherwise, use the same version for transitive dependencies (`cardano-ledger`, `ouroboros-network`, etc.) with `cardano-node`
+* It should pin the major version of `cardano-node` for all packages
+* It should pin the first and second-major version of `plutus` for all packages
+
+`main` branch:
+
+* It should not update `cardano-node` to a new major-version. In other words, it should use a `cardano-node` version which is compatible with the current Cardano mainnet
+* It should use a `cardano-wallet` version which is compatible with the current `cardano-node` version
+
+== Working with the project
+
+=== How to submit an issue
+
+Issues can be filed in the https://github.com/input-output-hk/marconi/issues[GitHub Issue tracker].
+
+However, note that this is pre-release software, so we will not usually be providing support.
 
-## Architecture
-The Marconi component are:
+[[how-to-develop]]
+=== How to develop and contribute to the project
 
-* [marconi-core](./marconi-core)
-* [marconi-chain-indexer](./marconi-chain-index)
-* [marconi-sidechain](./marconi-sidechain)
+See link:CONTRIBUTING{outfilesuffix}[CONTRIBUTING], which describes our processes in more detail including development environments; and link:ARCHITECTURE{outfilesuffix}[ARCHITECTURE], which describes the structure of the repository.
 
-## Developement
-.....
+=== How to depend on the project from another Haskell project
 
-## System Requirements
+None of our libraries are on Hackage, unfortunately (many of our dependencies aren't either).
+So for the time being, you need to:
 
-The system requirements for `marconi-chain-index` and `marconi-sidechain` (with `node` running
-on the same machine are:
+. Add `plutus-apps` as a `source-repository-package` to your `cabal.project`.
+. Copy the `source-repository-package` stanzas from our `cabal.project` to yours.
+. Copy additional stanzas from our `cabal.project` as you need, e.g. you may need some of the `allow-newer` stanzas.
 
-.....
+The https://github.com/input-output-hk/plutus-starter[plutus-starter] project
+(deprecated) provides an example.
 
 == Licensing
 
-.....
+You are free to copy, modify, and distribute the Plutus Platform with
+under the terms of the Apache 2.0 license. See the link:./LICENSE[LICENSE]
+and link:./NOTICE[NOTICE] files for details.

__std__/cells/marconi/library/default.nix

@@ -8,8 +8,6 @@
 
   marconi-project = import ./marconi-project.nix block;
 
-  # plutus-core-objects-inv = import ./plutus-core-objects-inv.nix block;
-
   make-marconi-project = import ./make-marconi-project.nix block;
 
   gitignore-source = import ./gitignore-source.nix block;

__std__/cells/marconi/library/make-marconi-project.nix

@@ -74,19 +74,19 @@ let
           lib.mkIf (pkgs.stdenv.hostPlatform.isWindows) {
             packages = {
               # Add dll symlinks to the compoents we want to run.
-              plutus-core.components.tests.plutus-core-test.postInstall = symlinkDlls;
-              plutus-core.components.tests.plutus-ir-test.postInstall = symlinkDlls;
-              plutus-core.components.tests.untyped-plutus-core-test.postInstall = symlinkDlls;
-              plutus-ledger-api.components.tests.plutus-ledger-api-test.postInstall = symlinkDlls;
+              # plutus-core.components.tests.plutus-core-test.postInstall = symlinkDlls;
+              # plutus-core.components.tests.plutus-ir-test.postInstall = symlinkDlls;
+              # plutus-core.components.tests.untyped-plutus-core-test.postInstall = symlinkDlls;
+              # plutus-ledger-api.components.tests.plutus-ledger-api-test.postInstall = symlinkDlls;
 
               # These three tests try to use `diff` and the following could be used to make the
               # linux version of diff available.  Unfortunately the paths passed to it are windows style.
               # plutus-core.components.tests.plutus-core-test.build-tools = [ pkgs.buildPackages.diffutils ];
               # plutus-core.components.tests.plutus-ir-test.build-tools = [ pkgs.buildPackages.diffutils ];
               # plutus-core.components.tests.untyped-plutus-core-test.build-tools = [ pkgs.buildPackages.diffutils ];
-              plutus-core.components.tests.plutus-core-test.buildable = lib.mkForce false;
-              plutus-core.components.tests.plutus-ir-test.buildable = lib.mkForce false;
-              plutus-core.components.tests.untyped-plutus-core-test.buildable = lib.mkForce false;
+              # plutus-core.components.tests.plutus-core-test.buildable = lib.mkForce false;
+              # plutus-core.components.tests.plutus-ir-test.buildable = lib.mkForce false;
+              # plutus-core.components.tests.untyped-plutus-core-test.buildable = lib.mkForce false;
             };
           }
         )
@@ -123,37 +123,37 @@ let
             marconi-sidechain.doHaddock = deferPluginErrors;
             marconi-sidechain.flags.defer-plugin-errors = deferPluginErrors;
 
-            plutus-contract.doHaddock = deferPluginErrors;
-            plutus-contract.flags.defer-plugin-errors = deferPluginErrors;
-
-            plutus-e2e-tests.doHaddock = deferPluginErrors;
-            plutus-e2e-tests.flags.defer-plugin-errors = deferPluginErrors;
-            plutus-e2e-tests.preCheck = "
-              export CARDANO_CLI=${config.hsPkgs.cardano-cli.components.exes.cardano-cli}/bin/cardano-cli${pkgs.stdenv.hostPlatform.extensions.executable}
-              export CARDANO_NODE=${config.hsPkgs.cardano-node.components.exes.cardano-node}/bin/cardano-node${pkgs.stdenv.hostPlatform.extensions.executable}
-              export CARDANO_NODE_SRC=${src}
-            ";
-            plutus-e2e-tests.components.tests.plutus-e2e-tests-test.build-tools =
-              lib.mkForce (with pkgs.buildPackages; [ jq coreutils shellcheck lsof ]);
-
-            plutus-use-cases.doHaddock = deferPluginErrors;
-            plutus-use-cases.flags.defer-plugin-errors = deferPluginErrors;
-
-            plutus-ledger.doHaddock = deferPluginErrors;
-            plutus-ledger.flags.defer-plugin-errors = deferPluginErrors;
-
-            plutus-script-utils.doHaddock = deferPluginErrors;
-            plutus-script-utils.flags.defer-plugin-errors = deferPluginErrors;
-
-            plutus-example.doHaddock = deferPluginErrors;
-            plutus-example.flags.defer-plugin-errors = deferPluginErrors;
-            plutus-example.preCheck = "
-              export CARDANO_CLI=${config.hsPkgs.cardano-cli.components.exes.cardano-cli}/bin/cardano-cli${pkgs.stdenv.hostPlatform.extensions.executable}
-              export CARDANO_NODE=${config.hsPkgs.cardano-node.components.exes.cardano-node}/bin/cardano-node${pkgs.stdenv.hostPlatform.extensions.executable}
-              export CARDANO_SUBMIT_API=${config.hsPkgs.cardano-submit-api.components.exes.cardano-submit-api}/bin/cardano-submit-api${pkgs.stdenv.hostPlatform.extensions.executable}
-              export CREATE_SCRIPT_CONTEXT=${config.hsPkgs.plutus-example.components.exes.create-script-context}/bin/create-script-context${pkgs.stdenv.hostPlatform.extensions.executable}
-              export CARDANO_NODE_SRC=${src}
-            ";
+            # plutus-contract.doHaddock = deferPluginErrors;
+            # plutus-contract.flags.defer-plugin-errors = deferPluginErrors;
+
+            # plutus-e2e-tests.doHaddock = deferPluginErrors;
+            # plutus-e2e-tests.flags.defer-plugin-errors = deferPluginErrors;
+            # plutus-e2e-tests.preCheck = "
+            #   export CARDANO_CLI=${config.hsPkgs.cardano-cli.components.exes.cardano-cli}/bin/cardano-cli${pkgs.stdenv.hostPlatform.extensions.executable}
+            #   export CARDANO_NODE=${config.hsPkgs.cardano-node.components.exes.cardano-node}/bin/cardano-node${pkgs.stdenv.hostPlatform.extensions.executable}
+            #   export CARDANO_NODE_SRC=${src}
+            # ";
+            # plutus-e2e-tests.components.tests.plutus-e2e-tests-test.build-tools =
+            #   lib.mkForce (with pkgs.buildPackages; [ jq coreutils shellcheck lsof ]);
+
+            # plutus-use-cases.doHaddock = deferPluginErrors;
+            # plutus-use-cases.flags.defer-plugin-errors = deferPluginErrors;
+
+            # plutus-ledger.doHaddock = deferPluginErrors;
+            # plutus-ledger.flags.defer-plugin-errors = deferPluginErrors;
+
+            # plutus-script-utils.doHaddock = deferPluginErrors;
+            # plutus-script-utils.flags.defer-plugin-errors = deferPluginErrors;
+
+            # plutus-example.doHaddock = deferPluginErrors;
+            # plutus-example.flags.defer-plugin-errors = deferPluginErrors;
+            # plutus-example.preCheck = "
+            #   export CARDANO_CLI=${config.hsPkgs.cardano-cli.components.exes.cardano-cli}/bin/cardano-cli${pkgs.stdenv.hostPlatform.extensions.executable}
+            #   export CARDANO_NODE=${config.hsPkgs.cardano-node.components.exes.cardano-node}/bin/cardano-node${pkgs.stdenv.hostPlatform.extensions.executable}
+            #   export CARDANO_SUBMIT_API=${config.hsPkgs.cardano-submit-api.components.exes.cardano-submit-api}/bin/cardano-submit-api${pkgs.stdenv.hostPlatform.extensions.executable}
+            #   export CREATE_SCRIPT_CONTEXT=${config.hsPkgs.plutus-example.components.exes.create-script-context}/bin/create-script-context${pkgs.stdenv.hostPlatform.extensions.executable}
+            #   export CARDANO_NODE_SRC=${src}
+            # ";
 
             # FIXME: Haddock mysteriously gives a spurious missing-home-modules warning
             plutus-tx-plugin.doHaddock = false;

__std__/cells/marconi/packages/default.nix

@@ -1,10 +1,10 @@
 { inputs, cell }@block:
 {
-  combined-marconi-haddock = import ./combined-marconi-haddock.nix block;
+  combined-plutus-apps-haddock = import ./combined-plutus-apps-haddock.nix block;
 
-  read-the-docs-site = import ./read-the-docs-site.nix block;
+  # read-the-docs-site = import ./read-the-docs-site.nix block;
 
-  serve-readthedocs-site = import ./serve-readthedocs-site.nix block;
+  # serve-readthedocs-site = import ./serve-readthedocs-site.nix block;
 
   sphinx-markdown-tables = import ./sphinx-markdown-tables.nix block;
 
@@ -42,19 +42,15 @@
 
   stylish-haskell = import ./stylish-haskell.nix block;
 
-  sphinx-autobuild-readthedocs-site = import ./sphinx-autobuild-readthedocs-site.nix block;
-
-  sphinx-build-readthedocs-site = import ./sphinx-build-readthedocs-site.nix block;
-
-
-
-  pab-cli = import ./pab-cli.nix block;
+  # sphinx-autobuild-readthedocs-site = import ./sphinx-autobuild-readthedocs-site.nix block;
 
+  # sphinx-build-readthedocs-site = import ./sphinx-build-readthedocs-site.nix block;
 
   marconi-chain-index = import ./marconi-chain-index.nix block;
 
   marconi-sidechain = import ./marconi-sidechain.nix block;
 
+  plutus-chain-index = import ./plutus-chain-index.nix block;
 
   create-script-context = import ./create-script-context.nix block;