Initial structure for guidelines

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.

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)
+
+<details><summary>List of repositories of <b>GobstonesWeb2</b></summary><p>
+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.
+</p></details>
+
+## Repositories configuration
+
+**_< Discuss gobstones-script >_**
+
+## Basic functionalities
+
+**_< Discuss gobstones-core >_**
+
+
+[Back to Introduction](./introduction.md)
+
+[Back to Guidelines](../README.md).

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).

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)

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).

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\<username>`).
+   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).

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).

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
+<details><summary>In order to contribute to the development, you need to have <code>Node.js</code> and some package manager installed in your system, and understand how to use it with a given repository.
+</summary><p>
+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/).
+</p></details>
+
+<details><summary>Associated with <code>Node.js</code> 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 <code>npm</code> (Node Package Manager), installed together with <code>Node.js</code>, but there are others.
+</summary><p>
+A good starting point to know the basics on `npm` is [`npmjs.com`](https://docs.npmjs.com/about-npm).
+</p></details>
+
+<details><summary>Finally, we use <code>Typescript</code> for most of the development of new packages.
+</summary><p>
+A good starting point to know the basics on `Typescript` is [`typescriptlang.org`](https://www.typescriptlang.org/docs/).
+</p></details>
+
+<details><summary>One important addition for helping on the development is the IDE (Integrated Development Environment).
+Again, there are several ones, but many of us use <b>Visual Studio Code</b> (<code>VSCode</code>).
+</summary><p>
+A good starting point to know the basics on `VSCode` is [`code.visualstudio.com`](https://code.visualstudio.com/docs).
+</p></details>
+
+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).