Merge pull request #6 from gobstones/develop_guidelines_alan

Develop initial version of the Guidelines, closes #3

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/architecture.md

@@ -0,0 +1,59 @@
+# **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 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)
+
+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
+
+<details>
+    <summary>
+        <b>Expand full list</b>
+    </summary>
+    <p>
+    The complete list of repositories to be used on **GobstonesWeb2** (either planned or under development).
+    </p>
+
+* [`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-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-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,
+* [`gobstones-parser`](https://github.com/gobstones/gobstones-parser), a parser for Gobstones language v3.12,
+* [`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-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.
+
+</details>
+
+## Repositories configuration
+
+_< TO BE DONE: Discuss gobstones-script >_
+
+## Basic functionalities
+
+_< TO BE DONE: Discuss gobstones-core >_
+
+
+[Back to Introduction](../introduction.md).
+
+[Back to Guidelines](../../README.md).

sections/coding-standards/coding-standards.md

@@ -0,0 +1,73 @@
+# Coding standards and workflow for **GobstonesWeb2**
+
+## Workflow
+
+### 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 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 
+
+          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"_.
+
+
+
+## **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.
+
+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).
+ * 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.
+
+_< TO BE DONE: expand >_
+
+[Back to Introduction](../introduction.md).
+
+[Back to Guidelines](../../README.md).

sections/governance/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/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 DONE: describe flow of communication >_
+
+[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](./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](./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](./governance/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**](./coding-standards/coding-standards.md).
+
+[Back to Guidelines](../README.md).

sections/technologies/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/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 (`Console -> New Console`), and run
+
+   ```npm install```
+
+Voilà. You are now ready to start exploring the package.
+
+[Back to Technologies](./technologies.md).
+
+[Back to Introduction](../introduction.md).
+
+[Back to Guidelines](../../README.md).

sections/technologies/technologies.md

@@ -0,0 +1,71 @@
+# Technologies used in **GobstonesWeb2**
+
+**GobstonesWeb2** is based on `Node.js`, and `Typescript`, and several technologies associated with those.
+
+## The basics
+
+<!--- ------- --->
+<!--- 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.
+<details>
+<summary>Expand to view more about <code>Node.js</code>.</summary>
+
+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/).
+</details>
+
+---
+
+<!--- ------- --->
+<!---   npm   --->
+<!--- ------- --->
+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.
+<details>
+<summary>Expand to view more about <code>npm</code>.</summary>
+
+A good starting point to know the basics on `npm` is [`npmjs.com`](https://docs.npmjs.com/about-npm).
+</details>
+
+---
+
+<!--- ---------- --->
+<!--- Typescript --->
+<!--- ---------- --->
+Finally, we use `Typescript` for most of the development of new packages.
+<details>
+<summary>Expand to view more about <code>TypeScript</code>.</summary>
+
+`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/).
+</details>
+
+---
+
+<!--- ------- --->
+<!---   VSC   --->
+<!--- ------- --->
+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`).
+<details>
+<summary>Expand to view more about <b>Visual Studio Code</b></summary>
+
+A good starting point to know the basics on `VSCode` is [`code.visualstudio.com`](https://code.visualstudio.com/docs).
+</details>
+
+---
+
+<!--- --------------------- --->
+<!--- Installation tutorial --->
+<!--- --------------------- --->
+If you need help on installing these elements in your system, [consult our short tutorial](./installation-tutorial.md).
+
+## Other technologies
+
+_< TO BE DONE: explain rollup, nps, jest, prettier, eslint, editorconfig, typedoc... >_
+
+[Back to Introduction](../introduction.md).
+
+[Back to Guidelines](../../README.md).