From 1ce9c8756dc55d3900090b19d69ff5ed1efe027b Mon Sep 17 00:00:00 2001 From: fidel Date: Sat, 24 Dec 2022 15:16:01 -0300 Subject: [PATCH 1/7] Initial structure for guidelines --- README.md | 20 +++++------ sections/architecture.md | 47 ++++++++++++++++++++++++ sections/coding-standards.md | 22 ++++++++++++ sections/current-core-group.md | 20 +++++++++++ sections/diagram-of-components.svg | 1 + sections/governance.md | 26 ++++++++++++++ sections/installation-tutorial.md | 57 ++++++++++++++++++++++++++++++ sections/introduction.md | 24 +++++++++++++ sections/technologies.md | 38 ++++++++++++++++++++ 9 files changed, 243 insertions(+), 12 deletions(-) create mode 100644 sections/architecture.md create mode 100644 sections/coding-standards.md create mode 100644 sections/current-core-group.md create mode 100644 sections/diagram-of-components.svg create mode 100644 sections/governance.md create mode 100644 sections/installation-tutorial.md create mode 100644 sections/introduction.md create mode 100644 sections/technologies.md diff --git a/README.md b/README.md index 0d87ff2..6d39060 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,19 @@ -# gobstones-guidelines +# Guidelines to contribute to **GobstonesWeb2** development -This repository contains documentation on the platform architecture, design guidelines, contribution and others. +This repository contains documentation on the platform architecture, design guidelines, ways to contribute, and standards used, related to the development of **GobstonesWeb2**. -[![Licence](https://img.shields.io/github/license/gobstones/gobstones-guidelines?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-guidelines/blob/main/LICENSE) [![Version](https://img.shields.io/github/v/tag/gobstones/gobstones-guidelines?color=crimson&label=Version&logo=git-lfs&logoColor=white&sort=semver&style=plastic)](https://github.com/gobstones/gobstones-guidelines) +[![License](https://img.shields.io/github/license/gobstones/gobstones-guidelines?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-guidelines/blob/main/LICENSE) +[![Version](https://img.shields.io/github/v/tag/gobstones/gobstones-guidelines?color=crimson&label=Version&logo=git-lfs&logoColor=white&sort=semver&style=plastic)](https://github.com/gobstones/gobstones-guidelines) -If you are planning on contributing to the Gobstones Platform in any way, please start by reading the following guidelines. +If you are planning on contributing to the development of **GobstonesWeb2** in any way, please start by reading the following guidelines. Be sure to: -* Understand how the Gobstones Platform is organized in different repositories. +* Understand how **GobstonesWeb2** architecture is organized in different repositories. * Be aware of the relationships of all the different repositories. * Learn about the technologies being used in common through all projects. * Get to know the project governance chain and communication channels. * Maintain the code standards for all projects and code submissions. -## TODO -This should be completed. -Complete the code standards guidelines - - ## Contributing - -See the [Gobstones Platform Contributions Guidelines](https://github.com/gobstones/gobstones-guidelines) to contribute. +In order to contribute, be sure to understand everything defined in these guidelines. +Start at the [**Introduction**](./sections/introduction.md) guiding you through all the sections. diff --git a/sections/architecture.md b/sections/architecture.md new file mode 100644 index 0000000..7fb521c --- /dev/null +++ b/sections/architecture.md @@ -0,0 +1,47 @@ +# **Architecture of **GobstonesWeb2**** +The architecture of **GobstonesWeb2** combines several modules providing different functionalities +For each module, there will be a repository in the organization. +The guidelines ask for all repositories to share a basic configuration structure, and in order to ensure it, there is a special module, in repository [gobstones-scripts](https://github.com/gobstones/gobstones-scripts),that all repositories of **GobstonesWeb2** must depend on, providing the means to automate such sharing. +In this way, when the team decide to change something on the common configuration, all repositories can be easily updated. + +The architecture of **GobstonesWeb2** is established by the dependencies between the modules provided by the different repositories belonging to the project, as presented in the following diagram: + +![GobstonesWeb2 Architecture Diagram](./diagram-of-components.svg) + +
List of repositories of GobstonesWeb2

+The complete list of repositories to be used on **GobstonesWeb2** (either planned or under development). +* [`gobstones-admin-dashboard`](https://github.com/gobstones/gobstones/gobstones-admin-dashboard), a dashboard for the Gobstones server, +* [`gobstones-assertions`](https://github.com/gobstones/gobstones/gobstones-assertions), a static and semantic code analyzer for Gobstones language, +* [`gobstones-blocks`](https://github.com/gobstones/gobstones-blocks), a framework agnostic Gobstones Blockly component, +* [`gobstones-blocks-react`](https://github.com/gobstones/gobstones/gobstones-blocks-react), the REACT layer over gobstones-blocks, +* [`gobstones-board`](https://github.com/gobstones/gobstones/gobstones-board), a representation for Gobstones boards, +* [`gobstones-board-react`](https://github.com/gobstones/gobstones/gobstones-board-react), the REACT layer over the gobstones-board, +* [`gobstones-code-editor`](https://github.com/gobstones/gobstones/gobstones-code-editor), a code editor to use with Gobstones, +* [`gobstones-core`](https://github.com/gobstones/gobstones-core), a set of utility tools used through all GobstonesWeb2 repositories, +* [`gobstones-ide`](https://github.com/gobstones/gobstones-ide), the IDE component, with the actual environment, +* [`gobstones-gbb-parser`](https://github.com/gobstones/gobstones-gbb-parser), a parser/printer for GBB (Gobstones Board) file format, +* [`gobstones-guidelines`](https://github.com/gobstones/gobstones/gobstones-guidelines), fundamental documentation to contribute to GobstonesWeb2, +* [`gobstones-lang`](https://github.com/gobstones/gobstones/gobstones-lang), a compiler for Gobstones language, +* [`gobstones-lang-intl`](https://github.com/gobstones/gobstones-lang-intl), translation for Gobstones language built-ins and keywords, +* [`gobstones-lint`](https://github.com/gobstones/gobstones/gobstones-lint), a linter for Gobstones language, +* [`gobstones-markdown-view`](https://github.com/gobstones/gobstones/gobstones-markdown-view), a markdown viewer for Gobstones, +* [`gobstones-parser`](https://github.com/gobstones/gobstones-parser), a parser for Gobstones language v3.12, +* [`gobstones-refactors`](https://github.com/gobstones/gobstones/gobstones-refactors), a refactoring tool for Gobstones language +* [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts), common configuration for all GobstonesWeb2 repositories +* [`gobstones-server`](https://github.com/gobstones/gobstones/gobstones-server), the Gobstones server, +* [`gobstones-test`](https://github.com/gobstones/gobstones/gobstones-test), a unit testing framework for Gobstones language, +* [`gobstones-typechecker`](https://github.com/gobstones/gobstones/gobstones-typechecker), a typechecker for Gobstones language. +

+ +## Repositories configuration + +**_< Discuss gobstones-script >_** + +## Basic functionalities + +**_< Discuss gobstones-core >_** + + +[Back to Introduction](./introduction.md) + +[Back to Guidelines](../README.md). \ No newline at end of file diff --git a/sections/coding-standards.md b/sections/coding-standards.md new file mode 100644 index 0000000..6314691 --- /dev/null +++ b/sections/coding-standards.md @@ -0,0 +1,22 @@ +# Coding standards and workflow for **GobstonesWeb2** + +**TO BE DEVELOPED** + +## Notes to write about +About Github flow. +https://docs.github.com/en/get-started/quickstart/github-flow +The only exception is that merging of branches is done by the Technical Committee. + +Document all your code using Typedoc, and generate the documentation. + +Please follow this conventions for filenames: + * Names should be descriptive and be in english + * All lowercase with kebab-case should be used for filenames, with no spaces + (Except README, CONTRIBUTING and LICENSE that are all uppercase) + * Only use CamelCase for classes in TS, not documentation files. + + Kebab case -- or kebab-case -- is a programming variable naming convention where a developer replaces the spaces between words with a dash. Programming variable names should be descriptive. + +[Back to Introduction](./introduction.md) + +[Back to Guidelines](../README.md). \ No newline at end of file diff --git a/sections/current-core-group.md b/sections/current-core-group.md new file mode 100644 index 0000000..9a8cb06 --- /dev/null +++ b/sections/current-core-group.md @@ -0,0 +1,20 @@ +# Current **Core Group** of **Gobstones Project** + +The list of current members of the **Core Group** deciding all the major aspects of the **Gobstones Project** including the development of **GobstonesWeb2** are: + + * Pablo E. --Fidel-- Martínez López, [`github.com/fidel-ml`](https://github.com/fidel-ml) + * Alan Rodas, [`github.com/alanrodas`](https://github.com/alanrodas) + +There is also a list of close advisors, that sometimes are also involved in making decisions. They are, at present: + + * Gonzalo Pablo --Perla-- Fernández Florio, [`github.com/gpfernandezflorio`](https://github.com/gpfernandezflorio) + * Leonardo Marina, [`github.com/leomarinag`](https://github.com/leomarinag) + * Federico A. Sawady O'Connor, [`github.com/sawady`](https://github.com/sawady) + * Federico Aloi, [`github.com/faloi`](https://github.com/faloi) + * Pablo Barenbaum, [`github.com/foones`](https://github.com/foones) + +[Back to Governance](./governance.md) + +[Back to Introduction](./introduction.md) + +[Back to Guidelines](../README.md) diff --git a/sections/diagram-of-components.svg b/sections/diagram-of-components.svg new file mode 100644 index 0000000..d5abe2f --- /dev/null +++ b/sections/diagram-of-components.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/sections/governance.md b/sections/governance.md new file mode 100644 index 0000000..8d2e28e --- /dev/null +++ b/sections/governance.md @@ -0,0 +1,26 @@ +# Governance and flow of communication for **GobstonesWeb2** + +Project governance provides direction and defines decision making. +Flow of communication guarantees that all contributors are aware of the latest decisions in the project that may affect them. + +## Governance +**Gobstones Project** involves all the aspects of **Gobstones**, including the language, the didactics, and the environments. + +Although there is, still, no organized committee, there is a [**Core Group**](./current-core-group.md) of researchers and developers that currently take all major decisions regarding the language and the environments, thus providing direction, defining the metrics for validating impacts to the project, and providing the tools needed to communicate, deliver on requirements, etc. +We expect to be able to have a formal committee at some point. + +The **Gobstones Community** is integrated by all researchers, developers, and users interested in **Gobstones**. +You can [join the **Gobstones Community**](http://bit.ly/ComunidadGobstones). + +**GobstonesWeb2** is an open source project aimed at providing a new version of the current environment, with a solid architecture that is understandable, maintainable, and extensible. +The **Core Group** is actively engaged in complete a MVP, and all contributions are welcome. + +If you are interested in contributing to **GobstonesWeb2**, please understand the flow of communication, and also the standards we use for the development, as described in these [**Guidelines**](../README.md). + +## Flow of communication + +**TO BE DEVELOPED** + +[Back to Introduction](./introduction.md) + +[Back to Guidelines](../README.md). \ No newline at end of file diff --git a/sections/installation-tutorial.md b/sections/installation-tutorial.md new file mode 100644 index 0000000..3a8258e --- /dev/null +++ b/sections/installation-tutorial.md @@ -0,0 +1,57 @@ +# Instructions to install a repository, for newcomers + +## Installing on **WSL** for use with **VSCode** on **Windows** + +This brief tutorial is an explanation for beginners on how to use **VSCode**, using **WSL** on **Windows**. +You may read about [**VSCode** and **WSL**](https://code.visualstudio.com/docs) if you are not familiar with them, where a clear explanation of how to install both **VSCode** and **WSL** from scratch is given. + +You may test the packaged either using **VSCode** from **Windows** or on a new **WSL** window, but to be able to debug it, it is best to use a new **WSL** window. + +Let's go to the installation. Skip any steps that you already performed. + +1. Install **VSCode** and **WSL** on your machine. + +2. Then you will need to install `Node.js` on **WSL**. + For that, run + + ```sudo apt install npm``` + + (after updating your `apt` with `sudo apt-get update`, if needed) on a **WSL** terminal. + Check the success of installation with `node -v`. + +3. As you will also use `Typescript`, you will need to install it as well, by running + + ```npm install -g typescript``` + + Check the success of installation with `tsc -v`. + +4. Then clone (or fork) the repository you want to work with. + If you are not going to debug, you may use any **Windows** directory, but if you want to debug, you will need to clone on the **WSL** file system (usually `\\wsl.localhost\Ubuntu\home\`). + The tool to manage `git` repositories is built-in inside WSL, but if you are using **Windows**, you may need to install and configure a [**GIT manager for Windows**](https://gitforwindows.org/). + + **NOTE:** I tried to debug the component from inside **VSCode** running it directly on **Windows**, but I failed, so I went for the conservative approach. + + Remember to follow the guidelines described in [**Coding standards and workflow**](./coding-standards.md) regarding the use of branches and pull-requests if you are going to experiment. + +5. The next step is to open **VSCode**, and connect to a remote host to be able to run it inside **WSL**. + For that you use the `><` icon on the lower left corner of the window, and select `New WSL Window`. + The icon on the lower left corner should change to `>< WSL: Ubuntu`. + +6. The following step is to open the package folder using `Open Folder` (either from the `File` menu, the button on the `Explorer`, the link in the `Getting started` window, or by using the keyboard shortcut -- by default, `CTRL-K CTRL-O`). + +7. If needed, before proceeding with the final step, you may want to perform an update, running first + + ```npm update``` + +8. The final step is installing the component, by fetching all the dependencies. + For that, open a console (`CTRL-%60`), and run + + ```npm install``` + +Voilà. You are now ready to start exploring the package. + +[Back to Technologies](./technologies-used.md). + +[Back to Introduction](./introduction.md) + +[Back to Guidelines](../README.md). \ No newline at end of file diff --git a/sections/introduction.md b/sections/introduction.md new file mode 100644 index 0000000..f87ea47 --- /dev/null +++ b/sections/introduction.md @@ -0,0 +1,24 @@ + +# Introduction to the **GobstonesWeb2** guidelines + +There are 4 topics you need to understand before being able to contribute effectively to GobstonesWeb2. + +## Architecture of **GobstonesWeb2** +The architecture of **GobstonesWeb2** combines several modules providing different functionalities +Consult [explanations about the architecture](./sections/architecture.md). + +## Technologies used +**GobstonesWeb2** is based on `Node.js` and uses mainly `Typescript` and several technologies associated with those. +Consult what [technologies we use](./sections/technologies.md) and how to use them. + +## Governance and flow of communication +Project governance provides direction and defines decision making. +Flow of communication guarantees that all contributors are aware of the latest decisions in the project that may affect them. +Consult [**GobstonesWeb2** governance and flow of communication](./sections/governance.md). + +## Coding standards and workflow +We follow a series of standards when coding and naming elements, and also a specific workflow. +Please, be sure fo follow those standards when contributing to the project. +Consult [**Coding standards and workflow**](./sections/coding-standards.md). + +[Back to Guidelines](../README.md). \ No newline at end of file diff --git a/sections/technologies.md b/sections/technologies.md new file mode 100644 index 0000000..468854c --- /dev/null +++ b/sections/technologies.md @@ -0,0 +1,38 @@ +# Technologies used in **GobstonesWeb2** + +**GobstonesWeb2** is based on `Node.js`, and `Typescript`, and several technologies associated with those. + +## The basics +
In order to contribute to the development, you need to have Node.js and some package manager installed in your system, and understand how to use it with a given repository. +

+If you want to know more on `Node.js` there are a lot of good books and tutorials on it. +A good starting point to know the basics on `Node.js` is [`nodejs.org`](https://nodejs.org/en/about/). +

+ +
Associated with Node.js you will be using some package manager, to help you download, install, and administer all the packages needed for effective development. +The most common package managers is npm (Node Package Manager), installed together with Node.js, but there are others. +

+A good starting point to know the basics on `npm` is [`npmjs.com`](https://docs.npmjs.com/about-npm). +

+ +
Finally, we use Typescript for most of the development of new packages. +

+A good starting point to know the basics on `Typescript` is [`typescriptlang.org`](https://www.typescriptlang.org/docs/). +

+ +
One important addition for helping on the development is the IDE (Integrated Development Environment). +Again, there are several ones, but many of us use Visual Studio Code (VSCode). +

+A good starting point to know the basics on `VSCode` is [`code.visualstudio.com`](https://code.visualstudio.com/docs). +

+ +If you need help on installing these elements in your system, we provide a [short tutorial](./installation-tutorial.md). + +## Other technologies + +**TO BE DEVELOPED**: +(rollup, nps, jest, prettier, eslint, editorconfig, typedoc) + +[Back to Introduction](./introduction.md) + +[Back to Guidelines](../README.md). \ No newline at end of file From 10c07b1bca376dee1be9371825ed129cf0450b6b Mon Sep 17 00:00:00 2001 From: Alan Rodas Bonjour Date: Tue, 18 Apr 2023 14:18:03 -0300 Subject: [PATCH 2/7] PARTIAL: changes in structure and style --- sections/{ => architecture}/architecture.md | 33 ++++++++++++------- .../diagram-of-components.svg | 0 .../coding-standards.md | 0 .../{ => governance}/current-core-group.md | 0 sections/{ => governance}/governance.md | 0 sections/introduction.md | 10 +++--- .../installation-tutorial.md | 28 ++++++++-------- sections/{ => technologies}/technologies.md | 14 +++++--- 8 files changed, 50 insertions(+), 35 deletions(-) rename sections/{ => architecture}/architecture.md (85%) rename sections/{ => architecture}/diagram-of-components.svg (100%) rename sections/{ => coding-standards}/coding-standards.md (100%) rename sections/{ => governance}/current-core-group.md (100%) rename sections/{ => governance}/governance.md (100%) rename sections/{ => technologies}/installation-tutorial.md (84%) rename sections/{ => technologies}/technologies.md (85%) diff --git a/sections/architecture.md b/sections/architecture/architecture.md similarity index 85% rename from sections/architecture.md rename to sections/architecture/architecture.md index 7fb521c..638830c 100644 --- a/sections/architecture.md +++ b/sections/architecture/architecture.md @@ -1,28 +1,36 @@ -# **Architecture of **GobstonesWeb2**** +# **Architecture of **GobstonesWeb2**** The architecture of **GobstonesWeb2** combines several modules providing different functionalities For each module, there will be a repository in the organization. -The guidelines ask for all repositories to share a basic configuration structure, and in order to ensure it, there is a special module, in repository [gobstones-scripts](https://github.com/gobstones/gobstones-scripts),that all repositories of **GobstonesWeb2** must depend on, providing the means to automate such sharing. +The guidelines ask for all repositories to share a basic configuration structure, and in order to ensure it, there is a special module, in repository [gobstones-scripts](https://github.com/gobstones/gobstones-scripts),that all repositories of **GobstonesWeb2** must depend on and be created by, providing the means to automate such sharing. In this way, when the team decide to change something on the common configuration, all repositories can be easily updated. The architecture of **GobstonesWeb2** is established by the dependencies between the modules provided by the different repositories belonging to the project, as presented in the following diagram: ![GobstonesWeb2 Architecture Diagram](./diagram-of-components.svg) -
List of repositories of GobstonesWeb2

-The complete list of repositories to be used on **GobstonesWeb2** (either planned or under development). -* [`gobstones-admin-dashboard`](https://github.com/gobstones/gobstones/gobstones-admin-dashboard), a dashboard for the Gobstones server, -* [`gobstones-assertions`](https://github.com/gobstones/gobstones/gobstones-assertions), a static and semantic code analyzer for Gobstones language, -* [`gobstones-blocks`](https://github.com/gobstones/gobstones-blocks), a framework agnostic Gobstones Blockly component, +## Details about repositories of GobstonesWeb2 + +

+ + Expand full list + +

+ The complete list of repositories to be used on **GobstonesWeb2** (either planned or under development). +

+ +* [`gobstones-admin-dashboard`](https://github.com/gobstones/gobstones/gobstones-admin-dashboard), a dashboard for the Gobstones server, +* [`gobstones-assertions`](https://github.com/gobstones/gobstones/gobstones-assertions), a static and semantic code analyzer for Gobstones language, +* [`gobstones-blocks`](https://github.com/gobstones/gobstones-blocks), a framework agnostic Gobstones Blockly component, * [`gobstones-blocks-react`](https://github.com/gobstones/gobstones/gobstones-blocks-react), the REACT layer over gobstones-blocks, * [`gobstones-board`](https://github.com/gobstones/gobstones/gobstones-board), a representation for Gobstones boards, * [`gobstones-board-react`](https://github.com/gobstones/gobstones/gobstones-board-react), the REACT layer over the gobstones-board, * [`gobstones-code-editor`](https://github.com/gobstones/gobstones/gobstones-code-editor), a code editor to use with Gobstones, * [`gobstones-core`](https://github.com/gobstones/gobstones-core), a set of utility tools used through all GobstonesWeb2 repositories, -* [`gobstones-ide`](https://github.com/gobstones/gobstones-ide), the IDE component, with the actual environment, +* [`gobstones-ide`](https://github.com/gobstones/gobstones-ide), the IDE component, with the actual environment, * [`gobstones-gbb-parser`](https://github.com/gobstones/gobstones-gbb-parser), a parser/printer for GBB (Gobstones Board) file format, * [`gobstones-guidelines`](https://github.com/gobstones/gobstones/gobstones-guidelines), fundamental documentation to contribute to GobstonesWeb2, * [`gobstones-lang`](https://github.com/gobstones/gobstones/gobstones-lang), a compiler for Gobstones language, -* [`gobstones-lang-intl`](https://github.com/gobstones/gobstones-lang-intl), translation for Gobstones language built-ins and keywords, +* [`gobstones-lang-intl`](https://github.com/gobstones/gobstones-lang-intl), translation for Gobstones language built-ins and keywords, * [`gobstones-lint`](https://github.com/gobstones/gobstones/gobstones-lint), a linter for Gobstones language, * [`gobstones-markdown-view`](https://github.com/gobstones/gobstones/gobstones-markdown-view), a markdown viewer for Gobstones, * [`gobstones-parser`](https://github.com/gobstones/gobstones-parser), a parser for Gobstones language v3.12, @@ -31,7 +39,8 @@ The complete list of repositories to be used on **GobstonesWeb2** (either planne * [`gobstones-server`](https://github.com/gobstones/gobstones/gobstones-server), the Gobstones server, * [`gobstones-test`](https://github.com/gobstones/gobstones/gobstones-test), a unit testing framework for Gobstones language, * [`gobstones-typechecker`](https://github.com/gobstones/gobstones/gobstones-typechecker), a typechecker for Gobstones language. -

+ +
## Repositories configuration @@ -42,6 +51,6 @@ The complete list of repositories to be used on **GobstonesWeb2** (either planne **_< Discuss gobstones-core >_** -[Back to Introduction](./introduction.md) +[Back to Introduction](../introduction.md) -[Back to Guidelines](../README.md). \ No newline at end of file +[Back to Guidelines](../../README.md). \ No newline at end of file diff --git a/sections/diagram-of-components.svg b/sections/architecture/diagram-of-components.svg similarity index 100% rename from sections/diagram-of-components.svg rename to sections/architecture/diagram-of-components.svg diff --git a/sections/coding-standards.md b/sections/coding-standards/coding-standards.md similarity index 100% rename from sections/coding-standards.md rename to sections/coding-standards/coding-standards.md diff --git a/sections/current-core-group.md b/sections/governance/current-core-group.md similarity index 100% rename from sections/current-core-group.md rename to sections/governance/current-core-group.md diff --git a/sections/governance.md b/sections/governance/governance.md similarity index 100% rename from sections/governance.md rename to sections/governance/governance.md diff --git a/sections/introduction.md b/sections/introduction.md index f87ea47..4dd5d8f 100644 --- a/sections/introduction.md +++ b/sections/introduction.md @@ -5,20 +5,20 @@ There are 4 topics you need to understand before being able to contribute effect ## Architecture of **GobstonesWeb2** The architecture of **GobstonesWeb2** combines several modules providing different functionalities -Consult [explanations about the architecture](./sections/architecture.md). +Consult [explanations about the architecture](./architecture/architecture.md). ## Technologies used **GobstonesWeb2** is based on `Node.js` and uses mainly `Typescript` and several technologies associated with those. -Consult what [technologies we use](./sections/technologies.md) and how to use them. +Consult what [technologies we use](./technologies/technologies.md) and how to use them. ## Governance and flow of communication Project governance provides direction and defines decision making. Flow of communication guarantees that all contributors are aware of the latest decisions in the project that may affect them. -Consult [**GobstonesWeb2** governance and flow of communication](./sections/governance.md). +Consult [**GobstonesWeb2** governance and flow of communication](./governance/governance.md). ## Coding standards and workflow -We follow a series of standards when coding and naming elements, and also a specific workflow. +We follow a series of standards when coding and naming elements, and also a specific workflow. Please, be sure fo follow those standards when contributing to the project. -Consult [**Coding standards and workflow**](./sections/coding-standards.md). +Consult [**Coding standards and workflow**](./coding-standards/coding-standards.md). [Back to Guidelines](../README.md). \ No newline at end of file diff --git a/sections/installation-tutorial.md b/sections/technologies/installation-tutorial.md similarity index 84% rename from sections/installation-tutorial.md rename to sections/technologies/installation-tutorial.md index 3a8258e..7a7008a 100644 --- a/sections/installation-tutorial.md +++ b/sections/technologies/installation-tutorial.md @@ -2,7 +2,7 @@ ## Installing on **WSL** for use with **VSCode** on **Windows** -This brief tutorial is an explanation for beginners on how to use **VSCode**, using **WSL** on **Windows**. +This brief tutorial is an explanation for beginners on how to use **VSCode**, using **WSL** on **Windows**. You may read about [**VSCode** and **WSL**](https://code.visualstudio.com/docs) if you are not familiar with them, where a clear explanation of how to install both **VSCode** and **WSL** from scratch is given. You may test the packaged either using **VSCode** from **Windows** or on a new **WSL** window, but to be able to debug it, it is best to use a new **WSL** window. @@ -11,21 +11,21 @@ Let's go to the installation. Skip any steps that you already performed. 1. Install **VSCode** and **WSL** on your machine. -2. Then you will need to install `Node.js` on **WSL**. - For that, run +2. Then you will need to install `Node.js` on **WSL**. + For that, run - ```sudo apt install npm``` + ```sudo apt install npm``` - (after updating your `apt` with `sudo apt-get update`, if needed) on a **WSL** terminal. + (after updating your `apt` with `sudo apt-get update`, if needed) on a **WSL** terminal. Check the success of installation with `node -v`. -3. As you will also use `Typescript`, you will need to install it as well, by running +3. As you will also use `Typescript`, you will need to install it as well, by running ```npm install -g typescript``` Check the success of installation with `tsc -v`. -4. Then clone (or fork) the repository you want to work with. +4. Then clone (or fork) the repository you want to work with. If you are not going to debug, you may use any **Windows** directory, but if you want to debug, you will need to clone on the **WSL** file system (usually `\\wsl.localhost\Ubuntu\home\`). The tool to manage `git` repositories is built-in inside WSL, but if you are using **Windows**, you may need to install and configure a [**GIT manager for Windows**](https://gitforwindows.org/). @@ -33,19 +33,19 @@ Let's go to the installation. Skip any steps that you already performed. Remember to follow the guidelines described in [**Coding standards and workflow**](./coding-standards.md) regarding the use of branches and pull-requests if you are going to experiment. -5. The next step is to open **VSCode**, and connect to a remote host to be able to run it inside **WSL**. - For that you use the `><` icon on the lower left corner of the window, and select `New WSL Window`. +5. The next step is to open **VSCode**, and connect to a remote host to be able to run it inside **WSL**. + For that you use the `><` icon on the lower left corner of the window, and select `New WSL Window`. The icon on the lower left corner should change to `>< WSL: Ubuntu`. 6. The following step is to open the package folder using `Open Folder` (either from the `File` menu, the button on the `Explorer`, the link in the `Getting started` window, or by using the keyboard shortcut -- by default, `CTRL-K CTRL-O`). -7. If needed, before proceeding with the final step, you may want to perform an update, running first - +7. If needed, before proceeding with the final step, you may want to perform an update, running first + ```npm update``` -8. The final step is installing the component, by fetching all the dependencies. - For that, open a console (`CTRL-%60`), and run - +8. The final step is installing the component, by fetching all the dependencies. + For that, open a console (`Console -> New Console`), and run + ```npm install``` Voilà. You are now ready to start exploring the package. diff --git a/sections/technologies.md b/sections/technologies/technologies.md similarity index 85% rename from sections/technologies.md rename to sections/technologies/technologies.md index 468854c..b41dc99 100644 --- a/sections/technologies.md +++ b/sections/technologies/technologies.md @@ -3,11 +3,17 @@ **GobstonesWeb2** is based on `Node.js`, and `Typescript`, and several technologies associated with those. ## The basics -
In order to contribute to the development, you need to have Node.js and some package manager installed in your system, and understand how to use it with a given repository. -

-If you want to know more on `Node.js` there are a lot of good books and tutorials on it. + +In order to contribute to the development, you need to have Node.js and some package manager installed in your system, and understand how to use it with a given repository. + +

+Expand to view more about Node.js + + +If you want to know more on `Node.js` there are a lot of good books and tutorials on it. A good starting point to know the basics on `Node.js` is [`nodejs.org`](https://nodejs.org/en/about/). -

+ +
Associated with Node.js you will be using some package manager, to help you download, install, and administer all the packages needed for effective development. The most common package managers is npm (Node Package Manager), installed together with Node.js, but there are others. From 4ba176042d2a13d1712562bf14900b76e9d4429e Mon Sep 17 00:00:00 2001 From: fidel Date: Fri, 28 Apr 2023 16:35:28 -0300 Subject: [PATCH 3/7] Adjusts details asked by Alan --- sections/README.md | 0 sections/architecture/architecture.md | 34 ++++----- sections/coding-standards/coding-standards.md | 17 +++-- sections/governance/current-core-group.md | 6 +- sections/governance/governance.md | 4 +- .../technologies/installation-tutorial.md | 8 +- sections/technologies/technologies.md | 73 +++++++++++++------ 7 files changed, 86 insertions(+), 56 deletions(-) create mode 100644 sections/README.md diff --git a/sections/README.md b/sections/README.md new file mode 100644 index 0000000..e69de29 diff --git a/sections/architecture/architecture.md b/sections/architecture/architecture.md index 638830c..ad5b944 100644 --- a/sections/architecture/architecture.md +++ b/sections/architecture/architecture.md @@ -18,39 +18,39 @@ The architecture of **GobstonesWeb2** is established by the dependencies between The complete list of repositories to be used on **GobstonesWeb2** (either planned or under development).

-* [`gobstones-admin-dashboard`](https://github.com/gobstones/gobstones/gobstones-admin-dashboard), a dashboard for the Gobstones server, -* [`gobstones-assertions`](https://github.com/gobstones/gobstones/gobstones-assertions), a static and semantic code analyzer for Gobstones language, +* [`gobstones-admin-dashboard`](https://github.com/gobstones/gobstones-admin-dashboard), a dashboard for the Gobstones server, +* [`gobstones-assertions`](https://github.com/gobstones/gobstones-assertions), a static and semantic code analyzer for Gobstones language, * [`gobstones-blocks`](https://github.com/gobstones/gobstones-blocks), a framework agnostic Gobstones Blockly component, -* [`gobstones-blocks-react`](https://github.com/gobstones/gobstones/gobstones-blocks-react), the REACT layer over gobstones-blocks, -* [`gobstones-board`](https://github.com/gobstones/gobstones/gobstones-board), a representation for Gobstones boards, -* [`gobstones-board-react`](https://github.com/gobstones/gobstones/gobstones-board-react), the REACT layer over the gobstones-board, -* [`gobstones-code-editor`](https://github.com/gobstones/gobstones/gobstones-code-editor), a code editor to use with Gobstones, +* [`gobstones-blocks-react`](https://github.com/gobstones/gobstones-blocks-react), the REACT layer over gobstones-blocks, +* [`gobstones-board`](https://github.com/gobstones/gobstones-board), a representation for Gobstones boards, +* [`gobstones-board-react`](https://github.com/gobstones/gobstones-board-react), the REACT layer over the gobstones-board, +* [`gobstones-code-editor`](https://github.com/gobstones/gobstones-code-editor), a code editor to use with Gobstones, * [`gobstones-core`](https://github.com/gobstones/gobstones-core), a set of utility tools used through all GobstonesWeb2 repositories, * [`gobstones-ide`](https://github.com/gobstones/gobstones-ide), the IDE component, with the actual environment, * [`gobstones-gbb-parser`](https://github.com/gobstones/gobstones-gbb-parser), a parser/printer for GBB (Gobstones Board) file format, -* [`gobstones-guidelines`](https://github.com/gobstones/gobstones/gobstones-guidelines), fundamental documentation to contribute to GobstonesWeb2, -* [`gobstones-lang`](https://github.com/gobstones/gobstones/gobstones-lang), a compiler for Gobstones language, +* [`gobstones-guidelines`](https://github.com/gobstones/gobstones-guidelines), fundamental documentation to contribute to GobstonesWeb2, +* [`gobstones-lang`](https://github.com/gobstones/gobstones-lang), a compiler for Gobstones language, * [`gobstones-lang-intl`](https://github.com/gobstones/gobstones-lang-intl), translation for Gobstones language built-ins and keywords, -* [`gobstones-lint`](https://github.com/gobstones/gobstones/gobstones-lint), a linter for Gobstones language, -* [`gobstones-markdown-view`](https://github.com/gobstones/gobstones/gobstones-markdown-view), a markdown viewer for Gobstones, +* [`gobstones-lint`](https://github.com/gobstones/gobstones-lint), a linter for Gobstones language, +* [`gobstones-markdown-view`](https://github.com/gobstones/gobstones-markdown-view), a markdown viewer for Gobstones, * [`gobstones-parser`](https://github.com/gobstones/gobstones-parser), a parser for Gobstones language v3.12, -* [`gobstones-refactors`](https://github.com/gobstones/gobstones/gobstones-refactors), a refactoring tool for Gobstones language +* [`gobstones-refactors`](https://github.com/gobstones/gobstones-refactors), a refactoring tool for Gobstones language * [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts), common configuration for all GobstonesWeb2 repositories -* [`gobstones-server`](https://github.com/gobstones/gobstones/gobstones-server), the Gobstones server, -* [`gobstones-test`](https://github.com/gobstones/gobstones/gobstones-test), a unit testing framework for Gobstones language, -* [`gobstones-typechecker`](https://github.com/gobstones/gobstones/gobstones-typechecker), a typechecker for Gobstones language. +* [`gobstones-server`](https://github.com/gobstones/gobstones-server), the Gobstones server, +* [`gobstones-test`](https://github.com/gobstones/gobstones-test), a unit testing framework for Gobstones language, +* [`gobstones-typechecker`](https://github.com/gobstones/gobstones-typechecker), a typechecker for Gobstones language.
## Repositories configuration -**_< Discuss gobstones-script >_** +_< TO BE DONE: Discuss gobstones-script >_ ## Basic functionalities -**_< Discuss gobstones-core >_** +_< TO BE DONE: Discuss gobstones-core >_ -[Back to Introduction](../introduction.md) +[Back to Introduction](../introduction.md). [Back to Guidelines](../../README.md). \ No newline at end of file diff --git a/sections/coding-standards/coding-standards.md b/sections/coding-standards/coding-standards.md index 6314691..2e289e5 100644 --- a/sections/coding-standards/coding-standards.md +++ b/sections/coding-standards/coding-standards.md @@ -7,16 +7,19 @@ About Github flow. https://docs.github.com/en/get-started/quickstart/github-flow The only exception is that merging of branches is done by the Technical Committee. -Document all your code using Typedoc, and generate the documentation. +Document all your code using [Typedoc](https://typedoc.org/guides/overview/), and generate the documentation. -Please follow this conventions for filenames: - * Names should be descriptive and be in english +Please follow this conventions for filenames. + * Names should be descriptive and in english. * All lowercase with kebab-case should be used for filenames, with no spaces - (Except README, CONTRIBUTING and LICENSE that are all uppercase) + (Except README, CONTRIBUTING and LICENSE that are all uppercase). * Only use CamelCase for classes in TS, not documentation files. - Kebab case -- or kebab-case -- is a programming variable naming convention where a developer replaces the spaces between words with a dash. Programming variable names should be descriptive. + Kebab case -- or kebab-case -- is a programming variable naming convention where a developer replaces the spaces between words with a dash. + Programming variable names should be descriptive. -[Back to Introduction](./introduction.md) +_< TO BE DONE: expand >_ -[Back to Guidelines](../README.md). \ No newline at end of file +[Back to Introduction](../introduction.md). + +[Back to Guidelines](../../README.md). \ No newline at end of file diff --git a/sections/governance/current-core-group.md b/sections/governance/current-core-group.md index 9a8cb06..69be3d0 100644 --- a/sections/governance/current-core-group.md +++ b/sections/governance/current-core-group.md @@ -13,8 +13,8 @@ There is also a list of close advisors, that sometimes are also involved in maki * Federico Aloi, [`github.com/faloi`](https://github.com/faloi) * Pablo Barenbaum, [`github.com/foones`](https://github.com/foones) -[Back to Governance](./governance.md) +[Back to Governance](./governance.md). -[Back to Introduction](./introduction.md) +[Back to Introduction](../introduction.md). -[Back to Guidelines](../README.md) +[Back to Guidelines](../../README.md). diff --git a/sections/governance/governance.md b/sections/governance/governance.md index 8d2e28e..bf4265e 100644 --- a/sections/governance/governance.md +++ b/sections/governance/governance.md @@ -15,11 +15,11 @@ You can [join the **Gobstones Community**](http://bit.ly/ComunidadGobstones). **GobstonesWeb2** is an open source project aimed at providing a new version of the current environment, with a solid architecture that is understandable, maintainable, and extensible. The **Core Group** is actively engaged in complete a MVP, and all contributions are welcome. -If you are interested in contributing to **GobstonesWeb2**, please understand the flow of communication, and also the standards we use for the development, as described in these [**Guidelines**](../README.md). +If you are interested in contributing to **GobstonesWeb2**, please understand the flow of communication, and also the standards we use for the development, as described in these [**Guidelines**](../../README.md). ## Flow of communication -**TO BE DEVELOPED** +_< TO BE DONE: describe flow of communication >_ [Back to Introduction](./introduction.md) diff --git a/sections/technologies/installation-tutorial.md b/sections/technologies/installation-tutorial.md index 7a7008a..29e2df2 100644 --- a/sections/technologies/installation-tutorial.md +++ b/sections/technologies/installation-tutorial.md @@ -31,7 +31,7 @@ Let's go to the installation. Skip any steps that you already performed. **NOTE:** I tried to debug the component from inside **VSCode** running it directly on **Windows**, but I failed, so I went for the conservative approach. - Remember to follow the guidelines described in [**Coding standards and workflow**](./coding-standards.md) regarding the use of branches and pull-requests if you are going to experiment. + Remember to follow the guidelines described in [**Coding standards and workflow**](../coding-standards/coding-standards.md) regarding the use of branches and pull-requests if you are going to experiment. 5. The next step is to open **VSCode**, and connect to a remote host to be able to run it inside **WSL**. For that you use the `><` icon on the lower left corner of the window, and select `New WSL Window`. @@ -50,8 +50,8 @@ Let's go to the installation. Skip any steps that you already performed. Voilà. You are now ready to start exploring the package. -[Back to Technologies](./technologies-used.md). +[Back to Technologies](./technologies.md). -[Back to Introduction](./introduction.md) +[Back to Introduction](../introduction.md). -[Back to Guidelines](../README.md). \ No newline at end of file +[Back to Guidelines](../../README.md). \ No newline at end of file diff --git a/sections/technologies/technologies.md b/sections/technologies/technologies.md index b41dc99..9aa51ed 100644 --- a/sections/technologies/technologies.md +++ b/sections/technologies/technologies.md @@ -4,41 +4,68 @@ ## The basics -In order to contribute to the development, you need to have Node.js and some package manager installed in your system, and understand how to use it with a given repository. - -
-Expand to view more about Node.js - - + + + +In order to contribute to the development, you need to have `Node.js` and some package manager installed in your system, and understand how to use it with a given repository. +
+Expand to view more about Node.js. + If you want to know more on `Node.js` there are a lot of good books and tutorials on it. A good starting point to know the basics on `Node.js` is [`nodejs.org`](https://nodejs.org/en/about/). -
-
Associated with Node.js you will be using some package manager, to help you download, install, and administer all the packages needed for effective development. -The most common package managers is npm (Node Package Manager), installed together with Node.js, but there are others. -

+--- + + + + +Associated with `Node.js` you will be using some package manager, to help you download, install, and administer all the packages needed for effective development. +The most common package managers is `npm` (Node Package Manager), installed together with `Node.js`, but there are others. +

+Expand to view more about npm. + A good starting point to know the basics on `npm` is [`npmjs.com`](https://docs.npmjs.com/about-npm). -

+
+ +--- -
Finally, we use Typescript for most of the development of new packages. -

+ + + +Finally, we use `Typescript` for most of the development of new packages. +

+Expand to view more about TypeScript. + +`Typescript` is a programming language based on `Javascript`, with the addition of types, thus +providing a type error detection mechanism. A good starting point to know the basics on `Typescript` is [`typescriptlang.org`](https://www.typescriptlang.org/docs/). -

+
+ +--- + + + + +One important addition for helping on the development is the IDE (Integrated Development Environment). +Again, there are several ones, but many of us use **Visual Studio Code** (`VSCode`). +
+Expand to view more about Visual Studio Code -
One important addition for helping on the development is the IDE (Integrated Development Environment). -Again, there are several ones, but many of us use Visual Studio Code (VSCode). -

A good starting point to know the basics on `VSCode` is [`code.visualstudio.com`](https://code.visualstudio.com/docs). -

+
+ +--- -If you need help on installing these elements in your system, we provide a [short tutorial](./installation-tutorial.md). + + + +If you need help on installing these elements in your system, [consult our short tutorial](./installation-tutorial.md). ## Other technologies -**TO BE DEVELOPED**: -(rollup, nps, jest, prettier, eslint, editorconfig, typedoc) +_< TO BE DONE: explain rollup, nps, jest, prettier, eslint, editorconfig, typedoc... >_ -[Back to Introduction](./introduction.md) +[Back to Introduction](../introduction.md). -[Back to Guidelines](../README.md). \ No newline at end of file +[Back to Guidelines](../../README.md). \ No newline at end of file From 96abda3b8d28547cc741e4813aec030adf9b85a8 Mon Sep 17 00:00:00 2001 From: fidel Date: Fri, 28 Apr 2023 16:59:44 -0300 Subject: [PATCH 4/7] [PARTIA:L:] Addition of lang-def to the list... --- sections/architecture/architecture.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sections/architecture/architecture.md b/sections/architecture/architecture.md index ad5b944..676fbe2 100644 --- a/sections/architecture/architecture.md +++ b/sections/architecture/architecture.md @@ -8,6 +8,8 @@ The architecture of **GobstonesWeb2** is established by the dependencies between ![GobstonesWeb2 Architecture Diagram](./diagram-of-components.svg) +We are currently working in redesigning some of the modules into new grouping. Expect changes on this graphic in the future. + ## Details about repositories of GobstonesWeb2
@@ -30,6 +32,7 @@ The architecture of **GobstonesWeb2** is established by the dependencies between * [`gobstones-gbb-parser`](https://github.com/gobstones/gobstones-gbb-parser), a parser/printer for GBB (Gobstones Board) file format, * [`gobstones-guidelines`](https://github.com/gobstones/gobstones-guidelines), fundamental documentation to contribute to GobstonesWeb2, * [`gobstones-lang`](https://github.com/gobstones/gobstones-lang), a compiler for Gobstones language, +* [`gobstones-lang-def`](https://github.com/gobstones/gobstones-lang-def), a new module that will replace `gobstones-lang-intl` and `gobstones-parser` (currently not in the diagram). * [`gobstones-lang-intl`](https://github.com/gobstones/gobstones-lang-intl), translation for Gobstones language built-ins and keywords, * [`gobstones-lint`](https://github.com/gobstones/gobstones-lint), a linter for Gobstones language, * [`gobstones-markdown-view`](https://github.com/gobstones/gobstones-markdown-view), a markdown viewer for Gobstones, From 3e6021d001b19c3ac12620eb1b4fef66816f3744 Mon Sep 17 00:00:00 2001 From: fidel Date: Sat, 17 Jun 2023 09:41:34 -0300 Subject: [PATCH 5/7] Basic workflow --- sections/coding-standards/coding-standards.md | 43 ++++++++++++++++++- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/sections/coding-standards/coding-standards.md b/sections/coding-standards/coding-standards.md index 2e289e5..9f12bc0 100644 --- a/sections/coding-standards/coding-standards.md +++ b/sections/coding-standards/coding-standards.md @@ -1,11 +1,50 @@ # Coding standards and workflow for **GobstonesWeb2** -**TO BE DEVELOPED** +## Workflow -## Notes to write about +### Module creation + +**TO BE DONE:** how to create a module + +### Module cloning +In order to start working on a module, you first has to clone it to your local machine. +Then you run + + npm install + +in order to install the different packages the module uses. + +### Working on an issue +If you want to work on an issue on the package, and it is not already in the issue-tracker, +create the new issue in the organization as your first step. +You must take care of: + * defining the right assignees and labels, + * associating the issue with the corresponding project, and + * giving the right status to the issue (usually: _"Todo"_). +Be also sure of give the issue a proper name and to describe the tasks required. + +Once the issue is on the issue-tracker, its status is _"Todo"_, and it was not assigned to someone else: + * assign the issue to yourself, + * change the status to _"In Progress"_, and + * create a branch for the issue. + +In your local clone checkout the new issue-branch, and work on the change. +When commiting, in the message describe briefly the things you modified. + +When you finish your changes, and before doing a pull-request, you must: + * be sure all tests pass, and the test coverage is enough (with `npm run test`), + * generate the documentation (with `npm run doc` -- take care no warnings for wrong links are produced), and + * build your module (with `npm run build`). +After that, you made the pull-request, and ask for revision. +Remember to indicate in the pull-request subject that it closes the corresponding issue, and change the status of the issue to _"Requested for revision"_. + + + +## **TO BE DEVELOPED:** Notes to write about About Github flow. https://docs.github.com/en/get-started/quickstart/github-flow The only exception is that merging of branches is done by the Technical Committee. +Will we use it? Document all your code using [Typedoc](https://typedoc.org/guides/overview/), and generate the documentation. From 4d0c59c969e607fa944e2a0b6ca4ad39782f20c2 Mon Sep 17 00:00:00 2001 From: fidel Date: Sat, 17 Jun 2023 09:45:25 -0300 Subject: [PATCH 6/7] [PARTIAL] Highlight commands --- sections/coding-standards/coding-standards.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/sections/coding-standards/coding-standards.md b/sections/coding-standards/coding-standards.md index 9f12bc0..07a9507 100644 --- a/sections/coding-standards/coding-standards.md +++ b/sections/coding-standards/coding-standards.md @@ -32,9 +32,18 @@ In your local clone checkout the new issue-branch, and work on the change. When commiting, in the message describe briefly the things you modified. When you finish your changes, and before doing a pull-request, you must: - * be sure all tests pass, and the test coverage is enough (with `npm run test`), - * generate the documentation (with `npm run doc` -- take care no warnings for wrong links are produced), and - * build your module (with `npm run build`). + * be sure all tests pass, and the test coverage is enough + + npm run test + + * generate the documentation, taking care that no warnings for wrong links are produced + + npm run doc + + * build your module. + + npm run build + After that, you made the pull-request, and ask for revision. Remember to indicate in the pull-request subject that it closes the corresponding issue, and change the status of the issue to _"Requested for revision"_. From 16be8b8ed54c80bb69ea1bf1ef8e48143ae8b966 Mon Sep 17 00:00:00 2001 From: fidel Date: Sat, 17 Jun 2023 09:48:47 -0300 Subject: [PATCH 7/7] [PARTIAL] Fix typo --- sections/coding-standards/coding-standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/coding-standards/coding-standards.md b/sections/coding-standards/coding-standards.md index 07a9507..30761a0 100644 --- a/sections/coding-standards/coding-standards.md +++ b/sections/coding-standards/coding-standards.md @@ -29,7 +29,7 @@ Once the issue is on the issue-tracker, its status is _"Todo"_, and it was not a * create a branch for the issue. In your local clone checkout the new issue-branch, and work on the change. -When commiting, in the message describe briefly the things you modified. +When committing, in the message describe briefly the things you modified. When you finish your changes, and before doing a pull-request, you must: * be sure all tests pass, and the test coverage is enough