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

publish v0.14.0 #148

Merged
merged 9 commits into from
Mar 10, 2023
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
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
134 changes: 42 additions & 92 deletions docs/charon/charon-cli-reference.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Before starting the cluster creation, you will need to collect one Ethereum addr
cd charon-distributed-validator-node

# Create your charon ENR private key, this will create a charon-enr-private-key file in the .charon directory
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.13.0 create enr
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.14.0 create enr
```

You should expect to see a console output like
Expand Down
2 changes: 1 addition & 1 deletion docs/int/quickstart/group/quickstart-group-operator.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git
cd charon-distributed-validator-node

# Create your charon ENR private key, this will create a charon-enr-private-key file in the .charon directory
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.13.0 create enr
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.14.0 create enr
```

You should expect to see a console output like
Expand Down
5 changes: 3 additions & 2 deletions docs/int/quickstart/quickstart-alone.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Run the following command:

```sh
# Create a distributed validator cluster
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.13.0 create cluster --withdrawal-address="0x000000000000000000000000000000000000dead" --nodes 6 --threshold 5
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.14.0 create cluster --withdrawal-address="0x000000000000000000000000000000000000dead" --nodes 6 --threshold 5
```

This command will create a subdirectory `.charon/cluster`. In it are six folders, one for each charon node created. Each folder contains partial private keys that together make up the distributed validator described in `.charon/cluster/cluster-lock.json`.
Expand Down Expand Up @@ -136,7 +136,8 @@ which needs a prysm beacon node to work alongside a REST based beacon node. Here
docker compose -f docker-compose.yml -f compose-prysm.yml -f docker-compose.override.yml up --build
```

Note: Support for prysm VCs with is in experimental phase as prysm doesn't provide complete support of REST API compatible validator client.
Note: Support for prysm VCs is in experimental phase as prysm doesn't provide [complete support](https://github.com/prysmaticlabs/prysm/issues/11580)
of REST API compatible validator client.
xenowits marked this conversation as resolved.
Show resolved Hide resolved

## Feedback

Expand Down
6 changes: 3 additions & 3 deletions docs/int/quickstart/quickstart-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git
cd charon-distributed-validator-node

# Create your charon ENR private key, this will create a charon-enr-private-key file in the .charon directory
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.13.0 create enr
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.14.0 create enr
```

You should expect to see a console output like
Expand All @@ -59,7 +59,7 @@ Finally, share your ENR with the leader or creator so that he/she can proceed to

3. Run the `charon create dkg` command that generates DKG cluster-definition.json file.
```
docker run --rm -v "$(pwd):/opt/charon" --env-file .env.create_dkg obolnetwork/charon:v0.13.0 create dkg
docker run --rm -v "$(pwd):/opt/charon" --env-file .env.create_dkg obolnetwork/charon:v0.14.0 create dkg
```

This command should output a file at `.charon/cluster-definition.json`. This file needs to be shared with the other operators in a cluster.
Expand All @@ -72,7 +72,7 @@ Every cluster member then participates in the DKG ceremony. For Charon v1, this

```
# Participate in DKG ceremony, this will create .charon/cluster-lock.json, .charon/deposit-data.json and .charon/validator_keys
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.13.0 dkg
docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v0.14.0 dkg
```

>This is a helpful [video walkthrough](https://www.youtube.com/watch?v=94Pkovp5zoQ&ab_channel=ObolNetwork).
Expand Down
5 changes: 5 additions & 0 deletions versioned_docs/version-v0.14.0/cg/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"label": "Contribution guidelines",
"position": 10,
"collapsed": true
}
57 changes: 57 additions & 0 deletions versioned_docs/version-v0.14.0/cg/bug-report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Filing a bug report

Bug reports are critical to the rapid development of Obol. In order to make the process quick and efficient for all parties, it is best to follow some common reporting etiquette when filing to avoid double issues or miscommunications.

## Checking if your issue exists

Duplicate tickets are a hindrance to the development process and, as such, it is crucial to first check through Charon's existing issues to see if what you are experiencing has already been indexed.

To do so, head over to the [issue page](https://github.com/ObolNetwork/charon/issues) and enter some related keywords into the search bar. This may include a sample from the output or specific components it affects.

If searches have shown the issue in question has not been reported yet, feel free to open up a new issue ticket.

## Writing quality bug reports

A good bug report is structured to help the developers and contributors visualize the issue in the clearest way possible. It's important to be concise and use comprehensive language, while also providing all relevant information on-hand. Use short and accurate sentences without any unnecessary additions, and include all existing specifications with a list of steps to reproduce the expected problem. Issues that cannot be reproduced **cannot be solved**.

If you are experiencing multiple issues, it is best to open each as a separate ticket. This allows them to be closed individually as they are resolved.

An original bug report will very likely be preserved and used as a record and sounding board for users that have similar experiences in the future. Because of this, it is a great service to the community to ensure that reports meet these standards and follow the template closely.


## The bug report template

Below is the standard bug report template used by all of Obol's official repositories.

```sh
<!--- Provide a general summary of the issue in the Title above -->

## Expected Behavior
<!--- What should be happening? -->

## Current Behavior
<!--- What happens instead? -->

## Steps to Reproduce
<!--- Provide a concise set of steps to reproduce this bug. -->
1.
2.
3.
4.
5.

## Detailed Description
<!--- Provide some context for the issue you are experiencing. -->

## Specifications
<!--- Provide some information regarding your local system. --->
Operating system:
Version(s) used:

## Possible Solution
<!--- (Optional) Suggest a fix, reason or implementation for the bug. -->

## Further Information
<!--- Anything else to add?
```

248 changes: 248 additions & 0 deletions versioned_docs/version-v0.14.0/cg/docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,248 @@
# Documentation standards

This section outlines the formatting standards presented within this documentation. In order to maintain continuity and quality, all pull requests must best conform to the specifics below.

## Content types

Walkthroughs and conceptual articles explained.

### Walkthroughs

The purpose of a walkthrough is to tell the user _how_ to do something. They do not need to convince the reader of something or explain a concept. Walkthroughs are a list of steps the reader must follow to achieve a process or function.

The vast majority of documentation within this manual falls under the _Walkthrough_ category. Walkthroughs are generally quite short, have a neutral tone, and teach the reader how to achieve a particular process or function. They present the reader with concrete steps on where to go, what to type, and things they should click on. There is little to no _conceptual_ information within walkthroughs.

#### Function or process

The end goal of a walkthrough is for the reader to achieve a very particular function.

Take an installation page for example: Following this walkthrough isn't going to teach the reader much about working with the decentralized web or what Obol is. Still, by the end, they'll have Charon installed on their computer.

#### Short length

Since walkthroughs cover one particular function or process, they tend to be quite short. The estimated reading time of a walkthrough is somewhere between 2 and 10 minutes. Most of the time, the most critical content in a walkthrough is presented in a numbered list. Images and gifs can help the reader understand what they should be doing.

If a walkthrough is converted into a video, that video should be no longer than 5 minutes.

#### Walkthrough structure

Walkthroughs are split into three major sections:

1. Context to the topics covered.
2. What we're about to do.
3. The steps we need to do.
4. Summary of what we just did, and potential next steps.

### Conceptual articles

Articles are written with the intent to inform and explain something. These articles don't contain any steps or actions that the reader has to perform _right now_.

These articles are vastly different in tone when compared to walkthroughs. Some topics and concepts can be challenging to understand, so creative writing and interesting diagrams are highly sought-after for these articles. Whatever writers can do to make a subject more understandable, the better.

#### Article goals

Use the following goals when writing conceptual articles:

| Goal | Keyword | Explanation |
| ------------- | ------------------------ | -------------------------------------------------------------------------------- |
| **Audience** | _Knowledgeable_ | Requires a certain amount of focus to understand. |
| **Formality** | _Neutral_ | Slang is restricted. **No you / your** -- explain informatively. |
| **Domain** | _Any_ | Usually _technical_, but depends on the article. |
| **Tone** | _Confident and friendly_ | The reader must feel confident that the writer knows what they're talking about. |
| **Intent** | _Describe_ | Tell the reader _why_ something does the thing that it does, or why it exists. |

#### Article structure

Articles are separated into five major sections:

1. Introduction to the thing we're about to explain.
2. What the thing is.
3. Why it's essential.
4. What other topics it relates to.
5. Summary review of what we just read.

When designing a tutorial, keep in mind the walkthroughs and articles that already exist, and note down any additional content items that would need to be completed before creating the tutorial.

# Grammar, formatting, and style

Here are some language-specific rules that the Obol documentation follows. If you use a writing service like [Grammarly](https://www.grammarly.com/), most of these rules are turned on by default.

### American English

The Obol documentation portal is written in American English.

### The Oxford comma

Follow each list of three or more items with a comma `,`:

| Use | Don't use |
| ----------------------------- | ---------------------------- |
| One, two, three, and four. | One, two, three and four. |
| Henry, Elizabeth, and George. | Henry, Elizabeth and George. |

### Acronyms

If you have to use an acronym, spell the full phrase first and include the acronym in parentheses `()` the first time it is used in each document. Exception: This generally isn't necessary for commonly-encountered acronyms like _EVM_, unless writing for a stand-alone article that may not be presented alongside project documentation.

> Virtual Machine (VM), Decentralized Web (DWeb).

## Formatting

How the Markdown syntax looks, and code formatting rules to follow.

## Style

The following rules explain how we organize and structure our writing. The rules outlined here are in addition to the [rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md) found within the [Markdownlinter extension](https://github.com/DavidAnson/vscode-markdownlint).

### Text

The following rules apply to editing and styling text.

#### Titles

1. All titles follow sentence structure. Only _names_ and _places_ are capitalized, along with the first letter of the title. All other letters are lower-case:

```markdown
## This is a title

### Only capitalize names and places

#### The capital city of France is Paris
```

2. Every article starts with a _front-matter_ title and description:

```markdown
---
title: Example article
description: This is a brief description that shows up in link teasers in services like Twitter and Slack.
---

## This is a subtitle

Example body text.
```

In the above example `title:` serves as a `<h1>` or `#` tag. There is only ever one title of this level in each article.

3. Titles do not contain punctuation. If you have a question within your title, rephrase it as a statement:

```markdown
<!-- This title is wrong. -->

## What is Charon?

<!-- This title is better. -->

## Charon explained
```

#### Bold text

Double asterisks `**` are used to define **boldface** text. Use bold text when the reader must interact with something displayed as text: buttons, hyperlinks, images with text in them, window names, and icons.

```markdown
In the **Login** window, enter your email into the **Username** field and click **Sign in**.
```

#### Italics

Underscores `_` are used to define _italic_ text. Style the names of things in italics, except input fields or buttons:

```markdown
Here are some American things:

- The _Spirit of St Louis_.
- The _White House_.
- The United States _Declaration of Independence_.

```

Quotes or sections of quoted text are styled in italics and surrounded by double quotes `"`:

```markdown
In the wise words of Winnie the Pooh _"People say nothing is impossible, but I do nothing every day."_
```

#### Code blocks

Tag code blocks with the syntax of the core they are presenting:

````markdown
```javascript
console.log(error);
```
````

#### List items

All list items follow sentence structure. Only _names_ and _places_ are capitalized, along with the first letter of the list item. All other letters are lowercase:

1. Never leave Nottingham without a sandwich.
2. Brian May played guitar for Queen.
3. Oranges.

List items end with a period `.`, or a colon `:` if the list item has a sub-list:

1. Charles Dickens novels:
1. Oliver Twist.
2. Nicholas Nickelby.
3. David Copperfield.
2. J.R.R Tolkien non-fiction books:
1. The Hobbit.
2. Silmarillion.
3. Letters from Father Christmas.

##### Unordered lists

Use the dash character `-` for un-numbered list items:

```markdown
- An apple.
- Three oranges.
- As many lemons as you can carry.
- Half a lime.
```

#### Special characters

Whenever possible, spell out the name of the special character, followed by an example of the character itself within a code block.

```markdown
Use the dollar sign `$` to enter debug-mode.
```

#### Keyboard shortcuts

When instructing the reader to use a keyboard shortcut, surround individual keys in code tags:

```bash
Press `ctrl` + `c` to copy the highlighted text.
```

The plus symbol `+` stays outside of the code tags.

### Images

The following rules and guidelines define how to use and store images.

#### Storage location

All images must be placed in the `/static/img` folder. For multiple images attributed to a single topic, a new folder within `/img/` may be needed.

#### File names

All file names are lower-case with dashes `-` between words, including image files:

```text
concepts/
├── content-addressed-data.md
├── images
│   └── proof-of-spacetime
│   └── post-diagram.png
└── proof-of-replication.md
└── proof-of-spacetime.md
```

_The framework and some information for this was forked from the original found on the [Filecoin documentation portal](https://docs.filecoin.io)_

5 changes: 5 additions & 0 deletions versioned_docs/version-v0.14.0/charon/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"label": "Charon",
"position": 3,
"collapsed": false
}
Loading