Improved READMEs for v0.1.1 (#54)

CHANGELOG.md

@@ -4,6 +4,13 @@ We roughly follow the ideas of [semantic versioning](https://semver.org/).
 Note that the versions "0.x.0" probably will include breaking changes.
 
 
+## v0.1.1 (December 2024)
+
+- Improved the READMEs in the packages `typir` and `typir-langium`.
+- Improved the CONTRIBUTING.md.
+- Improved source code for Tiny Typir in `api-example.test.ts`.
+
+
 ## v0.1.0 (December 2024)
 
 This is the first official release of Typir.

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing
 
-TODO
+Thank you for your interest in the Typir project!
+The following is a set of guidelines for contributing to Typir.
 
 
 ## Communication
@@ -15,6 +16,27 @@ In case you have a question, please look into the provided resources and documen
 If you don't find any answer there, feel free to use the discussions to get help.
 
 
+## Prerequisites
+
+- TypeScript
+- NodeJS
+- NPM
+
+
+## Things you might contribute
+
+- Feature requests, ideas: start a new GitHub discussion
+- Bug reports: create a new GitHub issue
+- Code contributions: see details below
+
+
+## Code contributions to Typir
+
+1. Create a new branch (or fork) of `main`.
+2. Do your changes, add corresponding test cases and comments/documentation and create a PR, which might link to issues or discussions.
+3. Wait for reviews and approvals, until your PR is merged.
+
+
 ## Release Process
 
 The release process for Typir is described in [RELEASE.md](./RELEASE.md).

README.md

@@ -129,7 +129,7 @@ Finally, we add a type related validation rule for our small example: In case we
 typir.validation.Collector.addValidationRule(node => {
     if (node instanceof AssignmentStatement) {
         return typir.validation.Constraints.ensureNodeIsAssignable(node.right, node.left, (actual, expected) => <ValidationMessageDetails>{ message:
-                    `The type '${actual.name}' is not assignable to the type '${expected.name}'.` });
+            `The type '${actual.name}' is not assignable to the type '${expected.name}'.` });
     }
     return [];
 });

examples/lox/package.json

@@ -1,7 +1,7 @@
 {
     "name": "typir-example-lox",
     "displayName": "lox",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "private": true,
     "description": "",
     "author": {
@@ -30,7 +30,7 @@
     "dependencies": {
         "commander": "~12.1.0",
         "langium": "~3.3.0",
-        "typir-langium": "~0.1.0",
+        "typir-langium": "~0.1.1",
         "vscode-languageclient": "~9.0.1",
         "vscode-languageserver": "~9.0.1"
     },

examples/ox/package.json

@@ -1,7 +1,7 @@
 {
     "name": "typir-example-ox",
     "displayName": "ox",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "private": true,
     "description": "",
     "author": {
@@ -30,7 +30,7 @@
     "dependencies": {
         "commander": "~12.1.0",
         "langium": "~3.3.0",
-        "typir-langium": "~0.1.0",
+        "typir-langium": "~0.1.1",
         "vscode-languageclient": "~9.0.1",
         "vscode-languageserver": "~9.0.1"
     },

packages/typir-langium/README.md

@@ -1,8 +1,12 @@
-# Typir integration for Langium
+# Typir-Langium: Typir integration for Langium
 
 Typir-Langium is a framework for type checking of languages developed with [Langium](https://langium.org),
 the language workbench for developing textual domain-specific languages (DSLs) in the web.
 
+Typir-Langium depends on Typir, the stand-alone library for type systems and type checking for software languages in the web, independent from any language workbench.
+Typir-Langium is a dedicated binding of Typir for DSLs which are developed with Langium.
+
+
 ## Installation
 
 ```bash
@@ -11,11 +15,10 @@ npm install typir-langium
 
 ## Documentation
 
-Will follow!
-
-Important design decisions:
+For an overview about the core features of Typir with a simple application example, see the [root README.md of the Typir project](/README.md).
 
-- Typir-Langium does not depend on `langium/lsp`, i.e. Typir-Langium can be used even for Langium-based DSLs which don't use LSP.
+Important design decision for Typir-Langium:
+Typir-Langium does not depend on `langium/lsp`, i.e. Typir-Langium can be used even for Langium-based DSLs which don't use LSP.
 
 Integrate Typir as additional Langium service into your DSL.
 
@@ -32,7 +35,7 @@ In case of a [multi-language project](https://langium.org/docs/recipes/multiple-
 
 ## Examples
 
-Look at the examples in the `examples` folder of the repo ([here](../../examples)). There we have some demo projects for you to get started.
+Look at the examples in the `examples/` folder of the repo ([here](../../examples)). There we have some demo projects for you to get started.
 
 ## License
 

packages/typir-langium/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typir-langium",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Typir binding for Langium",
   "homepage": "https://typir.org",
   "author": {
@@ -49,6 +49,6 @@
   "bugs": "https://github.com/TypeFox/typir/issues",
   "dependencies": {
     "langium": "~3.3.0",
-    "typir": "~0.1.0"
+    "typir": "~0.1.1"
   }
 }

packages/typir/README.md

@@ -1,26 +1,31 @@
-# Typir
+# Typir: Core functionality of Typir
+
+Typir is a library for type systems and type checking for software languages in the web.
+
+Typir is OpenSource, written in TypeScript, and follows pragmatic approaches for simplifying type checking in practical language engineering projects by providing default implementations for recurring problems.
+As a stand-alone library, Typir provides a TypeScript-API for language engineers without an additional, external DSL for formalizing types.
 
-Typir is a framework for type systems and type checking in the web.
 
 ## Installation
 
 ```bash
 npm install typir
 ```
 
-## Documentation
 
-Will follow!
+## Documentation
 
-Important design decisions:
+For an overview about the core features of Typir with a simple application example, see the [root README.md of the Typir project](/README.md).
 
-- Typir is a stand-alone library and has no dependencies to any existing language workbench.
+Important design decision:
+Typir is a stand-alone library and has no dependencies to any existing language workbench.
 
 
 ## Examples
 
 Look at the examples in the `examples` folder of the repo ([here](../../examples)). There we have some demo projects for you to get started.
 
+
 ## License
 
 [MIT License](/LICENSE)

packages/typir/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typir",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "General purpose type checking library",
   "homepage": "https://typir.org",
   "author": {

packages/typir/test/api-example.test.ts

@@ -10,23 +10,9 @@ import { describe, expect, test } from 'vitest';
 import { InferenceRuleNotApplicable, InferOperatorWithMultipleOperands, ValidationMessageDetails } from '../src/index.js';
 import { createTypirServices } from '../src/typir.js';
 
-describe('Tests for the new API', () => {
-    test('Experiments', async () => {
-        const typir = createTypirServices();
+describe('Tiny Typir', () => {
 
-        const booleanType = typir.factory.Primitives.create({ primitiveName: 'boolean' });
-        expect(booleanType).toBeTruthy();
-        const getBool = typir.factory.Primitives.get({ primitiveName: 'boolean' });
-        expect(getBool).toBe(booleanType);
-
-        typir.factory.Functions.create({ functionName: 'myFunction', inputParameters: [], outputParameter: undefined });
-
-        // operators
-        typir.factory.Operators.createBinary({ name: '&&', signature: { left: booleanType, right: booleanType, return: booleanType } });
-    });
-
-
-    test('Tiny Typir', async () => {
+    test('Set-up and test some expressions', async () => {
         const typir = createTypirServices(); // set-up the type system
 
         // primitive types