Merge pull request #451 from jvalue/release-0.1.0

Prepared release 0.1.0

Author: rhazn

apps/docs/docs/dev/02-dev-processes/04-release-jayvee-version.md

@@ -15,7 +15,8 @@ To indicate that, we only release alpha versions where the `version` is incremen
 For releasing a new version of Jayvee, you need to complete the following steps:
 
 1. Increment the version in the `package.json` file.
-2. Run `npx nx run docs:version-snapshot`.
-3. If you are on a feature or dev branch, merge into main.
-4. Create a GitHub release on the main branch. Attach a changelog.
-5. The CI/CD will deal with the rest.
+2. Run `npm i` to update the `package-lock.json`.
+3. Run `npx nx run docs:version-snapshot` to generate a snapshot of the docs for the previous version.
+4. If you are on a feature or dev branch, merge into main.
+5. Create a GitHub release on the main branch. Attach a changelog.
+6. The CI/CD will deal with the rest.

apps/docs/versioned_docs/version-0.1.0/dev/01-intro.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+---
+
+# Introduction for Jayvee Developers
+
+## How to contribute
+
+In order to contribute to the Jayvee project, please have a look at our [contribution guide](https://github.com/jvalue/jayvee/blob/main/CONTRIBUTING.md). Before planning a contribution, please read the [design principles](./05-design-principles.md) and consider if your changes fit the vision expressed there.
+
+The overall project is licensed under the `AGPL-3.0-only` license and is compliant to the [REUSE Specification](https://reuse.software/spec/) by the [Free Software Foundation Europe](https://fsfe.org/).
+Because of this, contributions are required to adhere to the license and follow that specification.
+More details on this topic can be found [here](./02-dev-processes/03-licensing-and-copyright.md).
+
+And last but not least, please read and follow our [code of conduct](https://github.com/jvalue/jayvee/blob/main/CODE_OF_CONDUCT.md).
+
+## Project overview
+
+The Jayvee repository is located [here](https://github.com/jvalue/jayvee) on GitHub.
+It uses an [Nx mono-repository](https://nx.dev/) setup and contains all related projects, most notably the Jayvee language server and interpreter.
+Please have a look at the [architecture overview](./03-architecture-overview.md) for more details.
+
+## Prerequisites
+
+Node.js and npm are required for development.
+It is recommended to use their LTS version to avoid any potential compatibility issues.
+Also, refer to this [quick start guide](https://github.com/jvalue/jayvee#development-quickstart) for developers.
+
+In order to run the Jayvee VS Code extension during development, VS Code is required as IDE.
+Using VS Code also allows installing the [Langium VS Code extension](https://marketplace.visualstudio.com/items?itemName=langium.langium-vscode) for better IDE support when working with Langium grammar files.
+
+## Resources for getting started
+
+### Langium
+
+- [**Langium documentation**](https://langium.org/docs/)
+- Practical examples using Langium:
+  - [Langium examples](https://github.com/langium/langium/tree/main/examples): Official example languages by Langium
+  - [Langium's grammar language](https://github.com/langium/langium/tree/main/packages/langium): The implementation of Langium's own grammar language
+  - [Language server for SQL](https://github.com/langium/langium-sql): An implementation of a language server for SQL
+  - [MiniLogo DSL](https://github.com/langium/langium-minilogo): A domain-specific language for drawing pictures
+  - [Lox language](https://github.com/langium/langium-lox): An implementation of the Lox scripting language (also see the "Crafting Interpreters" book below)
+  - [SimpleUI DSL](https://github.com/TypeFox/langium-ui-framework): A domain-specific language for generating user interfaces
+  - [STPA-DSL](https://github.com/kieler/stpa): A domain-specific language for System-Theoretic Process Analysis
+- [Langium playground](https://langium.org/playground/): A tool for testing Langium grammars and visualizing resulting ASTs
+- [Typefox blog](https://www.typefox.io/blog/): A blog by the company behind Langium, mostly posting Langium-related content.
+
+### Building compilers / interpreters / DSLs
+
+- [Crafting Interpreters](https://craftinginterpreters.com/contents.html): A book by Robert Nystrom on implementing an interpreter for the Lox scripting language
+- [DSL Engineering](https://voelter.de/dslbook/markusvoelter-dslengineering-1.0.pdf): A book by Markus Voelter on designing, implementing and using domain-specific languages
+- [Awesome Compilers](https://github.com/aalhour/awesome-compilers#readme): A list featuring many resources on compilers and interpreters

apps/docs/versioned_docs/version-0.1.0/dev/01-intro.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.1.0/dev/02-dev-processes/01-rfc-process.md

@@ -0,0 +1,13 @@
+---
+title: Language Design Process (RFCs)
+sidebar_position: 1
+---
+
+We use RFCs to discuss changes to the language before implementing them. You can have a look at all closed (accepted / rejected) RFCs [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aclosed+RFC+), and all RFCs under discussion [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aopen+RFC).
+
+If you want to contribute an RFC please follow these steps:
+1. Make a copy of the **template** at `rfc/0000-rfc-template.md` and place it into the `rfc` folder.
+2. Create a draft for the RFC on a new branch. Follow the `TODOs` in template to do so.
+3. Open a pull request with prefix `RFC <number>` in the title.
+4. Address the reviews. Consider opening a new PR if major things need to be addressed and the discussion log becomes too confusing.
+5. Once accepted, create an issue with the necessary steps to implement the RFC.

apps/docs/versioned_docs/version-0.1.0/dev/02-dev-processes/01-rfc-process.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.1.0/dev/02-dev-processes/02-debug-vs-code-extension.md

@@ -0,0 +1,25 @@
+---
+title: Debugging via the VS Code extension
+sidebar_position: 2
+---
+
+The VS Code extension of Jayvee can be used to interactively debug the language server.
+During development, when using VS Code as IDE, another instance of VS Code can be opened which has the most recent, locally built VS Code extension loaded.
+This can be achieved using the launch configuration `Run extension` the `Run and Debug` side-menu of VS Code or by pressing the `F5` key if that launch configuration is already selected there.
+
+Note that there is no file watching mechanism involved.
+So in order to reflect changes to the source code, the additional VS Code instance has to be **closed and reopened** as described above.
+
+## How to attach a debugger
+
+1. Use the launch configuration `Run extension` to open the additional VS Code instance with the extension loaded
+2. Use the launch configuration `Attach to Language Server` to attach the debugger
+
+Any set breakpoints should now be marked as active and pause the execution once they are reached.
+
+## How to view logs of the language server
+
+In the additional VS Code instance, it is possible to view the logs of the language server.
+They might also be helpful for debugging since any uncaught errors are logged with their stack trace by the Langium framework.
+
+To view the logs, open the bottom panel called `Output` and select `Jayvee` in the dropdown menu.

apps/docs/versioned_docs/version-0.1.0/dev/02-dev-processes/02-debug-vs-code-extension.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.1.0/dev/02-dev-processes/03-licensing-and-copyright.md

@@ -0,0 +1,69 @@
+---
+title: Licensing and copyright
+sidebar_position: 3
+---
+
+The [Jayvee repository](https://github.com/jvalue/jayvee) is REUSE compliant, meaning that it fulfills the 
+[REUSE Specification](https://reuse.software/spec/) by the [Free Software Foundation Europe](https://fsfe.org/) (FSFE).
+This makes clear under which license each project file is licensed under and who owns the copyright, not only for 
+humans but also for machines.
+
+This is done by explicitly adding copyright and licensing information to each file of the project. This is achieved 
+by either using a comment header or a separate `*.license` file in case comments are not possible.
+
+See <https://reuse.software/> more information.
+
+## What license is used in this project and who is the copyright holder?
+
+The entire project is licensed under [AGPL-3.0-only](https://spdx.org/licenses/AGPL-3.0-only.html), the
+license file can be found [here](https://github.com/jvalue/jayvee/blob/main/LICENSES/AGPL-3.0-only.txt).
+The copyright holder is the [Friedrich-Alexander-Universität Erlangen-Nürnberg](https://www.fau.eu/).
+
+## How to submit a REUSE compliant contribution?
+
+In case you want to contribute to the project, you will need to ensure that all of your contributed files are REUSE 
+compliant. In order to achieve this, you need to add a key-value pair for both copyright and licensing information 
+following this schema:
+
+```
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
+```
+
+In case a file allows comments, use single-line comments to add the copyright and licensing information at the top 
+of the file. Otherwise, create a corresponding `*.license` file with the text above as its content. You can have a 
+look at some existing project files to get an impression on it is done in practice.
+
+For files with common file extensions, you can use the [reuse CLI tool](https://github.com/fsfe/reuse-tool) to add 
+licensing and copyright information automatically.
+
+For more details, you can have a look at the [Getting Started tutorial](https://reuse.software/tutorial/) on the REUSE 
+website.
+
+## How to validate REUSE compliance?
+
+When you make a contribution and open a new pull request, the CI checks whether your contribution is REUSE compliant 
+using the [reuse CLI tool](https://github.com/fsfe/reuse-tool).
+
+In order to validate REUSE compliance in your local development environment, you have to install the
+[reuse CLI tool](https://github.com/fsfe/reuse-tool) and run the following command in the projects' root folder:
+
+```bash
+reuse lint
+```
+
+You can also set up a pre-commit hook, so the above command is run before each commit.
+See [here](https://reuse.readthedocs.io/en/latest/readme.html#run-as-pre-commit-hook) for details on how to set it up.
+
+## How to hide `*.license` files in IDEs
+
+During development, the file explorer of your IDE may be cluttered due to the numerous `*.license` files in the 
+project. Luckily, most IDEs allow hiding certain files, e.g. by specifying a pattern to exclude them from the 
+explorer.
+
+Below, you can find instructions on how to hide `*.license` files in commonly used IDEs:
+- **Visual Studio Code**: Add `**/*.license` to the
+[`files.exclude` setting](https://code.visualstudio.com/docs/getstarted/userinterface#_explorer) 
+- **WebStorm**: Add `*.license` to the
+[excluded files setting](https://www.jetbrains.com/help/webstorm/configuring-project-structure.html#exclude-by-pattern)

apps/docs/versioned_docs/version-0.1.0/dev/02-dev-processes/03-licensing-and-copyright.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.1.0/dev/02-dev-processes/04-release-jayvee-version.md

@@ -0,0 +1,21 @@
+---
+title: Releasing a new Jayvee version
+sidebar_position: 4
+---
+
+## Version Numbers
+
+In this early stage of the project we do not yet follow [semantic versioning](https://semver.org/) since we expect the introduction of breaking changes frequently.
+To indicate that, we only release alpha versions where the `version` is incremented with every release.
+- For the npm packages, we use the version `0.0.<version>`.
+- For the GitHub releases, we use the git tag `v0.0.<version>-alpha`.
+
+## Jayvee Release Procedure
+
+For releasing a new version of Jayvee, you need to complete the following steps:
+
+1. Increment the version in the `package.json` file.
+2. Run `npx nx run docs:version-snapshot`.
+3. If you are on a feature or dev branch, merge into main.
+4. Create a GitHub release on the main branch. Attach a changelog.
+5. The CI/CD will deal with the rest.