Add tutorials on writing engines for Anoma Specs #118
Closed
Conversation
This file contains hidden or 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
jonaprieto
added
priority:high
priority:undefined
priority:medium
and removed
priority:high
priority:undefined
labels
jonaprieto
changed the title
jonaprieto
added a commit
that referenced
this pull request
Sep 25, 2024
# Engine Families and Templates This PR introduces several changes and additions related to engine families, as discussed in Zug in q2 and q3 24'. ## 1. Engine Family Documentation A new page has been added to explain the concept of engine families: - [Engine Family Type](https://specs.anoma.net/pr-84/node_architecture/types/engine_family.html) This page provides detailed information about the `EngineFamily` and `Engine` types, including their structure and purpose within the Anoma ecosystem. ## 2. Engine Templates Template files have been added to serve as a starting point for creating new engines: - [Template Overview](https://specs.anoma.net/pr-84/node_architecture/engines/template_overview.html) - [Template Environment](https://specs.anoma.net/pr-84/node_architecture/engines/template_environment.html) - [Template Dynamics](https://specs.anoma.net/pr-84/node_architecture/engines/template_dynamics.html) - [Template Base File](https://specs.anoma.net/pr-84/node_architecture/engines/template.html) We have included a few conventions for writing and structuring your engine family for the specs in the tutorial section. ## 3. Ticker Engine Example A complete example of an engine family has been added, showcasing the Ticker engine: - [Ticker Engine Overview](https://specs.anoma.net/pr-84/node_architecture/engines/ticker_overview.html) - [Ticker Engine Environment](https://specs.anoma.net/pr-84/node_architecture/engines/ticker_environment.html) - [Ticker Engine Dynamics](https://specs.anoma.net/pr-84/node_architecture/engines/ticker_dynamics.html) - [Ticker Base File](https://specs.anoma.net/pr-84/node_architecture/engines/ticker.html) ## 4. Tutorial Updates The tutorials section has been updated to include information about engines in Anoma: - [Engines in Anoma](https://specs.anoma.net/pr-84/tutorial/engines/index.html) - [Engine Writing Conventions](https://specs.anoma.net/pr-84/tutorial/engines/writing_conventions.html) We'll add more tutorials in the future to make the writing process easier, making it easy to copy and paste. For now, we want to test whether our proposal accommodates the original goal and write specs in terms of engine instance interaction. This PR is required for: - #119 and - #118. --------- Co-authored-by: Jonathan Cubides <jonathan.cubides@uib.no> Co-authored-by: Anoma Research <arts@heliax.dev> Co-authored-by: Anthony Hart <soobtoob@gmail.com>
Base automatically changed from
heindel/templates-engines-n-guarded-actions
to
v2
September 25, 2024 19:04
|
Oh wow. This needs a lot of rework. :S |
jonaprieto
force-pushed
the
engine-writing-tutorial
branch
from
c48abc4 to
21f78c6
Compare
commit 40d38e4 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Sat Sep 28 04:47:49 2024 +0200 Fix CI issues: JS assets, deprecated Github actions versions, privacy plugin for MkDocs (#172) - Add Mathjax source code because of the `privacy` plugin. See https://squidfunk.github.io/mkdocs-material/plugins/privacy/?h=math#config.assets_exclude - Remove most of the privacy plugin options as they're creating a lot of js conflicts. - Pin GitHub action versions. See JamesIves/github-pages-deploy-action#1697 This also solves issues like: > The following actions use a deprecated Node.js version and will be forced to run on node20: jaxxstorm/action-install-gh-release@v1.10.0, actions/cache@v3, actions/setup-python@v4. For more info: https://github.blog/changelog/2024-03-07-github-actions-all-actions-will-run-on-node20-instead-of-node16-by-default/ commit c440dc1 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Fri Sep 27 20:12:07 2024 -0500 Fix Clean-up workflow commit caacba1 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Fri Sep 27 23:43:46 2024 +0200 Add Juvix version in the footer of Juvix code blocks (#136) After merging this PR, the Juvix compiler version will be visible in the footer of Juvix code blocks. This is important because using a different Juvix version may cause problems when using the code. It has already happened to me. <img width="870" alt="image" src="https://github.com/user-attachments/assets/c46661ab-9e6b-4a39-afe7-9de5db4efd8b"> <img width="869" alt="image" src="https://github.com/user-attachments/assets/7086a7ea-1dbe-4d49-84ff-f36b4bd79c85"> commit 8f5e206 Author: D. Reusche <code@degregat.net> Date: Thu Sep 26 17:41:28 2024 +0200 Updated transaction flow diagram (made by isheff). (#169) commit f443ea6 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Thu Sep 26 14:53:29 2024 +0200 fix PR site name (#167) This PR fixes a misconfiguration that prevents the PR number from being rendered correctly in the website name. Now it looks like this: <img width="598" alt="image" src="https://github.com/user-attachments/assets/82cf96d7-6111-4852-af5d-7cb6f35e6491"> Additionally, we can see some info used in the building process as in the picture. This only works for PRs. <img width="816" alt="image" src="https://github.com/user-attachments/assets/3aa35db1-4d90-4796-b58d-6a9236893eeb"> --------- Co-authored-by: Anoma Research <arts@heliax.dev> commit 5986392 Author: Tobias Heindel <tobias.heindel@gmail.com> Date: Thu Sep 26 14:49:18 2024 +0200 Heindel/issue 151 (#163) This removes all content that is irrelevant for the single node scenario; moreover, it renames v1 to v2 in some files (besides other minuscule changes). commit 171458e Author: Tobias Heindel <tobias.heindel@gmail.com> Date: Wed Sep 25 21:04:19 2024 +0200 Add templates for defining engine systems (#84) This PR introduces several changes and additions related to engine families, as discussed in Zug in q2 and q3 24'. A new page has been added to explain the concept of engine families: - [Engine Family Type](https://specs.anoma.net/pr-84/node_architecture/types/engine_family.html) This page provides detailed information about the `EngineFamily` and `Engine` types, including their structure and purpose within the Anoma ecosystem. Template files have been added to serve as a starting point for creating new engines: - [Template Overview](https://specs.anoma.net/pr-84/node_architecture/engines/template_overview.html) - [Template Environment](https://specs.anoma.net/pr-84/node_architecture/engines/template_environment.html) - [Template Dynamics](https://specs.anoma.net/pr-84/node_architecture/engines/template_dynamics.html) - [Template Base File](https://specs.anoma.net/pr-84/node_architecture/engines/template.html) We have included a few conventions for writing and structuring your engine family for the specs in the tutorial section. A complete example of an engine family has been added, showcasing the Ticker engine: - [Ticker Engine Overview](https://specs.anoma.net/pr-84/node_architecture/engines/ticker_overview.html) - [Ticker Engine Environment](https://specs.anoma.net/pr-84/node_architecture/engines/ticker_environment.html) - [Ticker Engine Dynamics](https://specs.anoma.net/pr-84/node_architecture/engines/ticker_dynamics.html) - [Ticker Base File](https://specs.anoma.net/pr-84/node_architecture/engines/ticker.html) The tutorials section has been updated to include information about engines in Anoma: - [Engines in Anoma](https://specs.anoma.net/pr-84/tutorial/engines/index.html) - [Engine Writing Conventions](https://specs.anoma.net/pr-84/tutorial/engines/writing_conventions.html) We'll add more tutorials in the future to make the writing process easier, making it easy to copy and paste. For now, we want to test whether our proposal accommodates the original goal and write specs in terms of engine instance interaction. This PR is required for: - #119 and - #118. --------- Co-authored-by: Jonathan Cubides <jonathan.cubides@uib.no> Co-authored-by: Anoma Research <arts@heliax.dev> Co-authored-by: Anthony Hart <soobtoob@gmail.com> commit c1d7efc Author: TG × ⊙ <*@tg-x.net> Date: Wed Sep 25 20:09:23 2024 +0200 CI fixes (#166) fixes #164 - CI: fix line breaks in `gh pr` command - CI: use poetry - CI: pin `insiders` patch version - python: pin `mkdocs-material` version - nix: update flake commit 64f4def Author: TG × ⊙ <*@tg-x.net> Date: Tue Sep 17 15:15:09 2024 +0200 Update nix flake (#150) commit 21e6c30 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Mon Sep 9 18:25:25 2024 +0200 add actor model bib entries (#147) commit 83ba6af Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Thu Sep 5 01:32:23 2024 -0500 Show PR number in the site name (#135) commit 841d970 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Thu Sep 5 01:09:07 2024 -0500 Refactor tutorial for wiki-style links (#134) commit 613031b Author: Christopher Goes <cwgoes@pluranimity.org> Date: Thu Sep 5 08:05:24 2024 +0200 Update basic abstractions (#127) Update the "Basic Abstractions" section, incorporating the proposals & discussions: - [Here](https://research.anoma.net/t/data-function-encoding/719) for data & function encoding - [Here](https://research.anoma.net/t/towards-a-general-proof-type/732) for general proof & assumption types The proof page is not finished. I think we should just have a session about this at the retreat. --------- Co-authored-by: Anoma Research <arts@heliax.dev> Co-authored-by: Jonathan Cubides <jonathan.cubides@uib.no> commit 6effc90 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Sep 4 04:00:05 2024 +0200 Add support for wiki-style links spreading multilines (#133) This PR closes - #113 and also adds a list of wikilinks used on each page. This behaviour can be override setting `list_wikilinks` to `false` in the page's front matter. See the tutorial page regarding wikilinks for more info. commit c8d6a3f Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Tue Sep 3 22:51:28 2024 +0200 Fix minors issues with directories and filenams (#132) commit b224999 Author: Anthony Hart <soobtoob@gmail.com> Date: Mon Sep 2 11:12:54 2024 -0400 Translate SML Identity definitions to Juvix. (#130) This translates the SML definitions found here: https://anoma.github.io/nspec/v2/system_architecture/identity/index.html into Juvix. The text in between the code is also just copy/pasted from the identity file linked, so it may not all make sense now that the SML has been swapped out. - https://anoma.github.io/nspec/pr-130/system_architecture/identity/identity.html --------- Co-authored-by: Anoma Research <arts@heliax.dev> Co-authored-by: Jonathan Cubides <jonathan.cubides@uib.no> commit d660e87 Author: Christopher Goes <cwgoes@pluranimity.org> Date: Mon Sep 2 17:11:13 2024 +0200 Add RMv3 content (#131) This is basically #109 "manually rebased" on the `v2` branch. The only change is that I omitted the proving system definition as we're already moved that elsewhere. This content will need to be edited and cleaned up a bit in the future to fit the rest of the specs but I wanted to get it in for now so that we can clarify things for engineering. --------- Co-authored-by: Anoma Research <arts@heliax.dev> Co-authored-by: Yulia Khalniyazova <juliajarskilli@gmail.com> Co-authored-by: Michael <20623991+heueristik@users.noreply.github.com> commit e55b5c0 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Aug 21 21:23:42 2024 +0200 Add a few Juvix defs from pr-84 (#128) commit 9ef6858 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Aug 14 18:54:18 2024 -0500 Add new link for ARTs in the footer commit 4ea43e9 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Aug 14 17:37:40 2024 -0500 Fix CI build. new environ var. BRANCH commit 598207e Author: Christopher Goes <cwgoes@pluranimity.org> Date: Wed Aug 14 23:35:08 2024 +0200 Refactor scope, basic types, and application architecture sections (#104) Please review this PR primarily for _structure_ - updates to content in these sections will come later, as some of the relevant discussions are still in progress on the forums (e.g. [here](https://research.anoma.net/t/proper-abstraction-of-instruction-sets-virtual-machines/663/15)). Tasks in this PR: - [x] Reorganize per https://research.anoma.net/t/notes-on-system-architecture/659/3 - [x] Update basic types and port/remove old content in the node-architecture section. - [x] Work out protocol desiderata section, including distributed intent machines, IFC, and heterogeneous trust, at least enough for the v2 specs, without dangling TODOs. After this PR is merged, I will write a follow-up based on the discussions in [this thread](https://research.anoma.net/t/data-function-encoding/719). --------- Co-authored-by: Jonathan Cubides <jonathan.cubides@uib.no> Co-authored-by: Anoma Research <arts@heliax.dev> commit 26d42b8 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Tue Aug 13 23:47:24 2024 -0500 Update mike config commit a8db019 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Aug 14 04:27:21 2024 +0200 Fix tutorial nav structure and broken links in the footer (#124) This PR includes some changes taken from pr-84 that were unrelated to that pr's topic. commit b4984a8 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Tue Aug 13 18:26:12 2024 -0500 Fix type: target_folder -> target-folder commit b270741 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Tue Aug 13 01:15:08 2024 -0500 Not fail inmediately, run snippet-extraction on original file commit cd0c712 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Tue Aug 13 07:44:47 2024 +0200 Fix support for Juvix Markdown snippets (#122) This PR adds (limited) support for snippeting Juvix Markdown files with the right syntax highlighting. This means that if you want to showcase highlighted Juvix code via snippets, you can either include the entire file or enclose the entire Juvix code block within a snippet section. 1. `--8<-- "./docs/...../YOURFILE.juvix.md` 2.  so you can use the included syntax: ``` --8<-- "./docs/...../YOURFILE.juvix.md:LABEL" ``` Extract excerpt by range line numbers such as `--8<-- "./docs/...../YOURFILE.juvix.md:10:13" may not work as expected, so please avoid it. Supporting snippet syntax within Juvix code blocks is future work and requires us to modify the compiler; currently, the translation to HTML removes comments. As a bonus, the PR solves an issue by including the entire file containing metadata. It automatically removes the whole chunk of metadata, so the snippet renders well now. PD: This is a good starting point for modifying the snippet machinery to include Elixir/Isabelle connections. commit 0ade96f Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Fri Aug 9 07:00:02 2024 +0200 Update index.md, remove tags commit 00c2951 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Fri Aug 9 06:56:37 2024 +0200 Improve look&feel, organized nav, hide extra links and move them to the footer (#121) commit 42c32ac Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Fri Aug 9 02:43:51 2024 +0200 Refactor tutorial organization and add a few more on conventions (#120) commit 1512d48 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Thu Aug 8 14:07:56 2024 -0500 [CI] Fix typo, missing boolean value commit 455e18c Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Thu Aug 8 13:28:48 2024 -0500 Make pre-commit happy commit 028c555 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Thu Aug 8 00:02:23 2024 -0500 [CI] Fix typos commit 373f37c Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Aug 7 23:58:19 2024 -0500 Remove old CI workflows commit d5ed6da Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Thu Aug 8 03:57:02 2024 +0200 Split CI workflows: deploy, pull-request, clean-ups (#100) This PR divides CI workflows into three parts: deploying the website for v* branch pushes, handling pull requests, and cleaning up closed pull requests. commit 79ed2a0 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Tue Aug 6 20:14:36 2024 +0200 Refactor file and folder names: add snake_case convention (#115) This PR fixes the following issues: - rename all files/folders to conform to the snake_case convention. This is the new standard. To run this refactor, I wrote [this script](https://gist.github.com/jonaprieto/f1d29c826de66c728ec5ee1e1649ed84) (however, it's pretty ad-hoc and needs double-checking as it changes not just files but file/folder references in the file contents). - trim trailing whitespaces - no large files - python scripts formatting and imports Pending is to update CI with these checks; at the moment, you can run the pre-commit checks with ``` pre-commit run --all-files ``` This PR is motivated by the ongoing integration with Isabelle/HOL. For example, the current folder and file names make it impossible for this system to import the generated files by Juvix. commit 0df604f Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Jun 19 22:37:56 2024 -0500 Fix warnings messages due to recent refactors (#105) This PR fixes only the warnings, we'll continue with the other warnings in another PR. commit ed77432 Author: Artem Gureev <67437331+agureev@users.noreply.github.com> Date: Wed Jun 19 17:55:11 2024 +0200 Change KV Storage Deletion Documentation (#64) Changes KV storage deletion documentation to refer to tombstoning of values rather than delition. Note that the declared value for the tombstone is kept implicit as that is implementation-dependent. - Closes #36 --------- Co-authored-by: Christopher Goes <cwgoes@pluranimity.org> Co-authored-by: Jonathan Cubides <jonathan.cubides@uib.no> commit 945b6f9 Author: Jonathan Cubides <jonathan.cubides@uib.no> Date: Wed Jun 19 10:36:01 2024 -0500 Improve Anoma main page and fix typos and wording (#101) Besides fixing typos found randomly, this PR aims to refactor the main page. It should contain a nice short description of what Anoma is and what the specification site is intended for. --------- Co-authored-by: Christopher Goes <cwgoes@pluranimity.org>
|
The preview of this PR failed to build. Check the logs. |
|
Instead of a fully fledged tutorial, we may actually rather want something in the style of a HOWTO + some explanation of how the all pieces fit together. The rough structure of such a HOWTO are:
The above is just a first draft for what this new issue could look like. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR provides
node-architecture/engines/*.The page to look at is: