Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feat/entries #417

Merged
merged 74 commits into from
Apr 15, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
74 commits
Select commit Hold shift + click to select a range
7643f79
chore: linebreak
mattyg Jan 8, 2024
4ffc260
refactor: split out hello world tutorial, forum tutorial, and deploym…
mattyg Dec 20, 2023
11ebbc9
feat: move example applications & tutorials links to 'References' page
mattyg Dec 20, 2023
284ac04
feat: entries page, content outline
mattyg Dec 20, 2023
4bdc2bb
fill in Entries page content, only a few TODOs
mattyg Dec 21, 2023
56318ff
chore: revert file formatting
mattyg Dec 23, 2023
37f7f03
feat: add mermaid chart rendering support
mattyg Dec 23, 2023
76ab497
feat: uncomment mermaid charts of entry update strategies
mattyg Dec 23, 2023
b5a3cc6
chore: minor tweaks
mattyg Jan 5, 2024
773f15b
revert: mermaid rendering code extracted into branch feat/mermaid-ren…
mattyg Jan 8, 2024
9f8cc19
chore: remove changes from other PR
mattyg Jan 8, 2024
12d2b13
chore: remove changes from other PR
mattyg Jan 8, 2024
c074d82
WIP - edits to entries page
pdaoust Feb 29, 2024
46e98ae
editorial consistency with style guide, text edits, remove target=_blank
pdaoust Mar 4, 2024
bfb940d
add note about 1:m and m:1 relationships
pdaoust Mar 4, 2024
44058ed
WIP
pdaoust Mar 7, 2024
a0e84e0
lots of content updates to entries guide
pdaoust Mar 8, 2024
309e406
convert mermaid to svg
pdaoust Mar 8, 2024
6a48284
fix broken menu in entries guide
pdaoust Mar 8, 2024
f43933f
add 'retrieve an entry' to page menu
pdaoust Mar 8, 2024
1b37c4c
text edits
pdaoust Mar 8, 2024
aaf0d24
fix entry details conversion
pdaoust Mar 8, 2024
14a2786
Merge branch 'main' into feat/entries
pdaoust Mar 25, 2024
4bf02ff
change title of build guide warning; move to top
pdaoust Mar 25, 2024
a598df4
move build guide to grandchild level in nav
pdaoust Mar 25, 2024
08f0c8d
add entries to build guide landing page
pdaoust Mar 25, 2024
5f98713
work on explanation of unopinionated updates and conflict resolution
pdaoust Mar 25, 2024
5c61963
add intro to 'working with data' section
pdaoust Mar 25, 2024
99ef006
fix spelling mistake and broken link
pdaoust Mar 25, 2024
32b0ee2
more spelling stuff
pdaoust Mar 25, 2024
8573e81
more work on the intro text of 'working with data' section
pdaoust Mar 25, 2024
4ebc573
Experimental: add category headers to side nav
pdaoust Mar 25, 2024
f4b8ac6
fix broken link to glossary
pdaoust Mar 25, 2024
51bcbe9
change link from home page to build guide
pdaoust Mar 25, 2024
6165e96
styling for guide topic lists
pdaoust Mar 26, 2024
41bd102
text edits
pdaoust Mar 26, 2024
550dfff
remove cuteness in under construction notice
pdaoust Mar 26, 2024
6a3c036
content edits
pdaoust Mar 26, 2024
6ba6ce1
more styling adjustments for topic list
pdaoust Mar 26, 2024
6df09ec
and one more
pdaoust Mar 26, 2024
f039e50
text editing work on entry topic
pdaoust Mar 26, 2024
7c4f064
more edits on entry topic
pdaoust Mar 26, 2024
9a0815f
fix formatting in some links
pdaoust Mar 26, 2024
6beee72
Merge branch 'main' into feat/entries
pdaoust Mar 28, 2024
c36391d
fix incomplete merge
pdaoust Mar 28, 2024
f54ea21
fix external links issue - plugin treats relative paths as hostnames
pdaoust Mar 28, 2024
bbaa300
update SVGs -- they don't look right tho
pdaoust Mar 28, 2024
a92860f
fix styling of SVG diagrams
pdaoust Mar 28, 2024
2255624
editing Entry page for brevity -- could use some more work
pdaoust Mar 28, 2024
f00cbd7
remove resolved todo comment about exact steps of a create
pdaoust Mar 29, 2024
c4724bb
ditto
pdaoust Mar 29, 2024
649285f
ditto
pdaoust Mar 29, 2024
bf6d59a
add further reading about distributed systems to entries and resources
pdaoust Mar 29, 2024
a11a46e
add links to live mermaid graphs in the todo comments
pdaoust Mar 29, 2024
72410ff
improve language around monotonicity -- not sure I succeeded :D
pdaoust Mar 29, 2024
34fb8e1
reorganise read section of entries page
pdaoust Mar 29, 2024
9943d49
add mention of scaffolding tool
pdaoust Mar 29, 2024
5cf1e8e
fix issue in entries on-page nav
pdaoust Mar 29, 2024
4d73a84
fix broken on-page nav hierarchy for entries
pdaoust Mar 29, 2024
9c127c1
Merge branch 'main' into feat/entries
pdaoust Mar 29, 2024
1feddd6
fix styling of nav hierarchy
pdaoust Mar 29, 2024
94db2f6
fix edge case of styled linked headers in topic pages
pdaoust Mar 29, 2024
f896777
chore: spelling
pdaoust Mar 29, 2024
bcf65de
comment out 'working with data'
pdaoust Mar 29, 2024
11937b1
link to 'working with data' on build page
pdaoust Mar 29, 2024
40e0ba5
normalise bullets
pdaoust Mar 29, 2024
e8fc6c9
normalise module paths
pdaoust Mar 29, 2024
3235b72
very tiny edit to clarify that all metadata can be got using get_details
pdaoust Apr 8, 2024
465bfdd
Merge branch 'main' into feat/entries
pdaoust Apr 15, 2024
fab479d
Merge branch 'main' into feat/entries
pdaoust Apr 15, 2024
ed26d78
remove manual TOC from entries page
pdaoust Apr 15, 2024
e4b5ff2
re-add preamble about what data is about
pdaoust Apr 15, 2024
0ea2e6e
fix mistake in lifecycle -- add bit about chain top ordering
pdaoust Apr 15, 2024
5617e6b
small updates to entries page -- last one, I think
pdaoust Apr 15, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .cspell/custom-words.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
# Dev Portal content
agent-centricity
Anwaar
Automerge
automerge
buildinputs
builtins
Brisebois
Expand All @@ -11,9 +13,13 @@ CRDT
d'Aoust
fixt
gnused
Hellerstein
imdb
IMDB
identicon
identicons
IPFS
Kleppmann
NixOS
nixpkgs
pkgs
Expand Down
1 change: 1 addition & 0 deletions .cspell/template-words.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ endlink
endmacro
endrenderlayoutblock
gtag
katex
layoutblock
MSIE
newblock
Expand Down
2 changes: 2 additions & 0 deletions .cspell/words-that-should-exist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ affordance
affordances
automations
birthdate
chrono
counterparties
counterparties'
counterparty
Expand All @@ -16,6 +17,7 @@ permissioned
permissivity
runtimes
sandboxed
scaffolder
spacebar
todo
todos
Expand Down
6 changes: 2 additions & 4 deletions 11ty-extensions/markdown-it-config.js
Original file line number Diff line number Diff line change
Expand Up @@ -81,10 +81,7 @@ const validateDetailsBlock = (params) => {

/* End Details Block code */

/**
* Configures Markdown-it lib plugins etc. Meant to be called from .eleventy.js
* @param {*} eleventyConfig
*/
// Set up the Markdown-it parser here.

const mdLib = markdownIt();

Expand All @@ -107,6 +104,7 @@ mdLib.use(markdownItContainer, "intro");
mdLib.use(markdownItContainer, "orientation");
mdLib.use(markdownItContainer, "storystep");
mdLib.use(markdownItContainer, "h-author");
mdLib.use(markdownItContainer, "topic-list");
mdLib.use(markdownItContainer, "output-block");

// Admonitions
Expand Down
7 changes: 6 additions & 1 deletion src/pages/_data/navigation/mainNav.json5
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,12 @@
{ title: "Lifecycle Events", url: "/concepts/11_lifecycle_events/" },
]
},
{ title: "Build", url: "/build/", children: []},
{ title: "Build", url: "/build/", children: [
{ title: "Working with Data", url: "/build/#working-with-data", children: [
{ title: "Entries", url: "/build/entries/" },
]},
]
},
{ title: "Resources", url: "/resources/", children: [
{ title: "HDK", url: "https://docs.rs/hdk", external: true },
{ title: "HDI", url: "https://docs.rs/hdi", external: true },
Expand Down
2 changes: 1 addition & 1 deletion src/pages/_includes/widgets/home-tiles.njk
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
{{ craneIcon() }}
<div class="text-wrapper">
<h2>Build Guide</h2>
<p>Learn how to write Holochain applications</p>
<p>Learn how to write and deploy Holochain applications</p>
</div>
{% endlinkTile %}

Expand Down
6 changes: 3 additions & 3 deletions src/pages/_includes/widgets/navigation.njk
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@
<ul class="nav-child-level {% if isCurrentParent %}open{% endif %}">
{% for childLink in navData %}
<li {% if childLink.url == page.url %} aria-current="page" {% endif %}>
<a href="{{ childLink.url }}" {% if childLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %} >
<{% if childLink.url %}a href="{{ childLink.url }}" {% if childLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %}{% else %}div{% endif %} class="nav-label">
<span>
{{ childLink.title }}
</span>
</a>
</{% if childLink.url %}a{% else %}div{% endif %}>

{% if childLink.children %}
{{ children(childLink.children, isCurrentParent, page) }}
Expand All @@ -29,7 +29,7 @@
{% set isCurrentParent = topLink.url == activeParent.url %}
<li {% if isCurrentParent %} data-is-current-parent="true" {% endif %}
{% if topLink.url == page.url %} aria-current="page" {% endif %} >
<a href="{{ topLink.url }}" {% if topLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %} >
<a href="{{ topLink.url }}" {% if topLink.external %}target="_blank" rel="noreferrer nofollow noopener external"{% endif %} class="nav-label">
<span>
{{ topLink.title }}
</span>
Expand Down
395 changes: 395 additions & 0 deletions src/pages/build/entries.md

Large diffs are not rendered by default.

11 changes: 0 additions & 11 deletions src/pages/build/guide/index.md

This file was deleted.

25 changes: 22 additions & 3 deletions src/pages/build/index.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,26 @@
---
title: Build on Holochain
title: Holochain Build Guide
---

Now that you've learned Holochain's [core concepts](/concepts/1_the_basics), [installed Holochain](/get-started/#2-installing-holochain-development-environment), and [built a basic hApp](/get-started/3-forum-app-tutorial/), it's time to deepen your Holochain knowledge to the point where you feel capable of using its full feature set to build complex applications.
!!! note In progress
This guide is under construction. Expect more content to be rapidly published in the first half of 2024.
!!!

The [Build Guide](/build/guide/) expands on the Core Concepts guide with code examples and a deeper level of detail on how to use various APIs and what they're doing in the background. Each page in this guide brings together all the functions and concepts you need in order to get a particular thing done.
::: intro
This Build Guide organizes everything you need to know about developing Holochain applications into individual topics. Each topic page stands alone as a comprehensive guide to using a given feature or implementing a given functionality. There are lots of code examples which make it clear how to do something yet are generic enough to be universally useful. These examples may not cover every single use case, though, so we'll point you to the reference documentation often.
:::

## Working with data

Shared data in a Holochain application is stored as a graph database of **bases** connected by **links**. A base is identified by a 32-byte identifier such as a hash or public key, and may have data and metadata associated with it. There are four types of bases:

* An **entry** is an arbitrary blob of bytes that your application code gives meaning to.
* An **agent ID** is a special type of entry that contains the public key of a participant in an application.
* An **action** records the act of manipulating the graph and contains metadata about the act, such as authorship and timestamp.
* An **external reference** is the ID of a resource that exists outside the database, such as the hash of an IPFS resource or the public key of an Ethereum address.

::: topic-list
### Topics {data-no-toc}

* [Entries](/build/entries/) --- creating, reading, updating, and deleting
:::
1 change: 0 additions & 1 deletion src/pages/concepts/2_application_architecture.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Application Architecture
tocData: false
---

::: intro
Expand Down
9 changes: 8 additions & 1 deletion src/pages/resources/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -581,7 +581,10 @@ A Holochain application design pattern, in which one [DHT](#distributed-hash-tab

#### Logical monotonicity

The property of a set of facts whereby the truth of prior facts are never negated by the addition of later facts. [CALM](#consistency-as-logical-monotonicity-calm-theorem) relies on functions that exhibit this property. For example, Holochain's [source chain](#source-chain) and [DHT](#distributed-hash-table-dht) only add new data without removing old data, simulating deletions and modifications ([CRUD](#create-read-update-delete-crud)) by recording actions which override the status of, but don't remove, the data they refer to.
The property of a system whereby [monotonicity](#monotonicity) is applied to state changes. Practically this means that state changes are only accumulated, never forgotten, so that the system's final state results from the application of all accumulated state changes. [CALM](#consistency-as-logical-monotonicity-calm-theorem) systems such as Holochain are logically monotonic. Two examples of this in Holochain are:

* An [agent](#agent)'s [source chain](#source-chain) is an event journal that only adds state change operations, never removes them.
* An application's [DHT](#distributed-hash-table-dht) only adds new data without removing old data, simulating deletions and modifications ([CRUD](#create-read-update-delete-crud)) by recording actions which override the status of, but don't remove, the data they refer to.

#### Membrane

Expand Down Expand Up @@ -614,6 +617,10 @@ An application architecture pattern that encourages small, single-purpose [back

An extension to [countersigning](#countersigning), in which a number of optional witnesses are also involved as [counterparties](#counterparty) signing the session, a majority of which must sign in order for the session to complete. One optional witness must also be nominated as the session's [enzyme](#enzyme).

#### Monotonicity

A property of a function whereby values are either non-decreasing or non-increasing (that is, values may stay the same, but if they change, they may only ever go up or go down). An example in Holochain can be found in the timestamps of an [agent](#agent)'s [source chain](#source-chain), where a source chain [action](#action) can never be earlier than the action that precedes it. See also [logical monotonicity](#logical-monotonicity).

#### Mutual sovereignty

The relationship between the autonomy of the individual and the collective intentions of the group. A successful [commons](#commons) finds a healthy tension between these opposites. Holochain's design is based on this principle, empowering [participants](#participant) to control their own identity and responses to their peers by equipping each of them with a full copy of the application's code. This code constitutes a formal, executable definition of the group's rules and norms, as [DNA](#dna) modules, so by running the application a participant consents to become a member of the group and be bound by those rules and norms.
Expand Down
12 changes: 11 additions & 1 deletion src/pages/resources/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ There are three main developer binaries, and one user-oriented binary. You can r

The developer community has created some useful utilities, libraries, and reusable modules for you to use in your own apps.

* [Syn](https://github.com/holochain/syn) provides back-end and front-end libraries for creating real-time collaboration apps.
* [Holochain Open Dev](https://github.com/holochain-open-dev/) is a collection of reusable zomes and template repos from the developer community.
* [`profiles`](https://github.com/holochain-open-dev/profiles) lets you store user profile information.
* [`peer-status`](https://github.com/holochain-open-dev/peer-status) lets peers communicate their status (e.g., 'online', 'busy', 'on holiday') with each other.
Expand Down Expand Up @@ -99,4 +100,13 @@ Studying existing Holochain applications and tutorials can provide valuable insi
While you'll learn a lot looking at the source code from the above GitHub projects, we've also produced some training material as a result of running courses in collaboration with our education partner Mythosthesia.

* [Developer training materials](https://github.com/holochain-immersive) from past courses
* [Self-paced training course](https://resources.holochain.org/self-paced-training-signup/) in video format
* [Self-paced training course](https://resources.holochain.org/self-paced-training-signup/) in video format

## Concepts useful for understanding and building distributed systems

Holochain builds on a wealth of research and knowledge about distributed systems. Here are some carefully picked resources to help you on your journey:

* [Keeping CALM: When Distributed Consistency is Easy](https://arxiv.org/abs/1901.01930), a paper by Joseph M Hellerstein and Peter Alvaro that lays down the mathematical foundation for distributed systems that don't need coordination protocols, such as Holochain.
* [CRDT.tech](https://crdt.tech), a resource for learning about conflict-free replicated data types (CRDTs), data structures that let multiple users make concurrent updates to a resource with little to no manual conflict resolution.
* [Yjs](https://yjs.dev/) and [Automerge](https://automerge.org/), two CRDTs that can operate on arbitrary JSON. Syn (mentioned above under [Libraries](#libraries)) uses Automerge.
* [Local-first software: You own your data, in spite of the cloud](https://github.com/holochain/syn), a paper by Martin Kleppmann et al of Ink & Switch that explores the user experience of local-first software built on CRDTs.
42 changes: 23 additions & 19 deletions src/scss/_navigation.scss
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,6 @@
transition: all .75s;
text-decoration: none;

// Add a span so that we can use the border to indicate current page and
// control the size of the indicator independent of the box size of the a tag
span {
display: inline-flex;
align-items: flex-end;
padding-left: $current-page-highlight-padding;
border-left: 4px solid transparent;

svg {
margin: 0 0 6px 6px;
}
}

@include externalLinkIcon($link-color);

&:hover {
Expand All @@ -50,6 +37,19 @@
}
}

// Add a span so that we can use the border to indicate current page and
// control the size of the indicator independent of the box size of the a tag
.nav-label span {
display: inline-flex;
align-items: flex-end;
padding-left: $current-page-highlight-padding;
border-left: 4px solid transparent;

svg {
margin: 0 0 6px 6px;
}
}

li {
margin-bottom: unset;

Expand Down Expand Up @@ -100,31 +100,35 @@
/* Because we want the whole row in which the nav link sits to be
clickable, we can't rely on just adding a blanket margin to
.nav-child-level. Instead, we add increasing padding to nested
block-display links, which means we have to do it manually for each
block-display wrappers, which means we have to do it manually for each
nesting level. This imposes a limit on how many nesting levels to
support, because we don't want to repeat the below code infinitely. */
a {
.nav-label {
padding: 3px 0 4px 12px;
}

div.nav-label {
font-style: italic;
}

ul.nav-child-level {
a {
.nav-label {
padding-left: 24px;
}

ul.nav-child-level {
a {
.nav-label {
padding-left: 36px;
}

ul.nav-child-level {
a {
.nav-label {
padding-left: 48px;
}

/* I think that's enough levels of nesting, don't you? */
ul.nav-child-level {
a {
.nav-label {
padding-left: 60px;
}
}
Expand Down
7 changes: 6 additions & 1 deletion src/scss/_svg-icons.scss
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,12 @@ $shovelIcon: url("data:image/svg+xml,%3Csvg%20viewBox%3D'0%200%201200%201200'%20
}
}

$pageIcon: url("data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 -150 1200 1200' xmlns='http://www.w3.org/2000/svg'%3E%3Cg%3E%3Cpath d='m806.4 1042.8c86.398 0 156-69.602 156-156v-474-1.1992-4.8008-1.1992c0-2.3984-1.1992-3.6016-2.3984-6 0-1.1992 0-1.1992-1.1992-2.3984s-1.1992-2.3984-2.3984-3.6016c0-1.1992-1.1992-1.1992-1.1992-2.3984-1.1992-1.1992-1.1992-2.3984-2.3984-3.6016l-1.1992-1.1992-232.8-219.6c-1.1992-1.1992-2.3984-2.3984-4.8008-3.6016 0 0-1.1992 0-1.1992-1.1992-1.1992-1.1992-2.3984-1.1992-4.8008-2.3984-1.1992 0-1.1992 0-2.3984-1.1992-1.1992 0-3.6016-1.1992-4.8008-1.1992h-1.1992c-2.3984 0-4.8008-1.1992-6-1.1992h-300c-86.398 0-156 69.602-156 156v573.6c0 86.398 69.602 156 156 156l412.8-0.003907zm-76.797-766.8 105.6 99.602h-105.6zm-420 610.8v-573.6c0-46.801 37.199-84 84-84h264v183.6c0 20.398 15.602 36 36 36h196.8v438c0 46.801-37.199 84-84 84h-412.8c-46.801 0-84-37.199-84-84z'/%3E%3Cpath d='m423.6 676.8h198c20.398 0 36-15.602 36-36 0-20.398-15.602-36-36-36h-198c-20.398 0-36 15.602-36 36 0 20.398 16.797 36 36 36z'/%3E%3Cpath d='m423.6 846h354c20.398 0 36-15.602 36-36s-15.602-36-36-36h-354c-20.398 0-36 15.602-36 36s16.797 36 36 36z'/%3E%3C/g%3E%3C/svg%3E");

@mixin addPageIcon() {
@include addInlineIcon(before, $pageIcon);
}

@mixin externalLinkIcon($color) {
$color-encoded: encodecolor($color);
&:not(.no-away), :not(.no-away) &, .no-away &.away {
Expand All @@ -82,4 +88,3 @@ $shovelIcon: url("data:image/svg+xml,%3Csvg%20viewBox%3D'0%200%201200%201200'%20
}
}
}

24 changes: 23 additions & 1 deletion src/scss/_widgets.scss
Original file line number Diff line number Diff line change
Expand Up @@ -344,6 +344,29 @@ a.link-tile {
}
}

/* A special styling for lists of links to sub-pages. Used in the build guide. */
.topic-list {
padding: 1em;
background-color: #f7f7f7;

/* Unless otherwise specified with `class="not-topic-page"`, links in a topic
list are assumed to point to topic pages. */
a:not(.not-topic-page, .header-anchor) {
font-weight: bold;
@include addPageIcon;
}

> :first-child {
margin-top: 0;
}

> :last-child {
margin-bottom: 0;
}
}

/* Enlarged text with a rule on the left side, meant to call out an interesting
paragran at the top of a page. */
.intro {
font-size: $fs-even-bigger;
border-left: 4px solid $cl-gray;
Expand All @@ -367,7 +390,6 @@ a.link-tile {
}

.storystep {

/* Horizontal rules can be used to break up content in a story step.
Make them nice and light. */
hr {
Expand Down