Skip to content

Commit 1fb22ee

Browse files
vknabelvknabel
committed
docs: added CONTRIBUTING.md
1 parent e7fd98e commit 1fb22ee

File tree

2 files changed

+135
-0
lines changed

2 files changed

+135
-0
lines changed

‎.vscode/extensions.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
3+
// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
4+
// List of extensions which should be recommended for users of this workspace.
5+
"recommendations": [
6+
"ms-vscode-remote.remote-containers",
7+
"golang.go",
8+
"vknabel.vscode-lithia"
9+
],
10+
// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
11+
"unwantedRecommendations": []
12+
}

‎CONTRIBUTING.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Contributing
2+
3+
First of all: **thank you** for your interest in contributing to this project and open source in general!
4+
5+
At first, contributing to Lithia might sound intimidating. _After all, it's a programming language, right?_
6+
But the bigger a topic is, the more aspects there are to consider and the more possibilities to contribute there are.
7+
8+
I'd really love to hear your feedback, ideas and suggestions. If you have any questions, feel free to ask them in the [Discussions](https://github.com/vknabel/lithia/discussions) or [Issues](https://github.com/vknabel/lithia/issues) section. You are able to shape this project.
9+
10+
**Table of Contents**
11+
12+
- [Contributing](#contributing)
13+
- [Code of Conduct](#code-of-conduct)
14+
- [Ways to Contribute](#ways-to-contribute)
15+
- [Using Lithia](#using-lithia)
16+
- [Reporting Bugs](#reporting-bugs)
17+
- [Driving Evolution](#driving-evolution)
18+
- [Writing Documentation](#writing-documentation)
19+
- [Writing Code or Tests](#writing-code-or-tests)
20+
- [Reviewing Pull Requests](#reviewing-pull-requests)
21+
- [Writing Libraries](#writing-libraries)
22+
- [Architecture](#architecture)
23+
- [Development](#development)
24+
- [Board](#board)
25+
26+
## Ways to Contribute
27+
28+
You can contribute to Lithia in many ways:
29+
30+
- [Using Lithia](#using-lithia)
31+
- [Reporting Bugs](#reporting-bugs)
32+
- [Driving Evolution](#driving-evolution)
33+
- [Writing Documentation](#writing-documentation)
34+
- [Writing Code or Tests](#writing-code-or-tests)
35+
- [Reviewing Pull Requests](#reviewing-pull-requests)
36+
- [Writing Libraries](#writing-libraries)
37+
38+
### Using Lithia
39+
40+
The best way to get comfortable with new tech is actually using it. And Lithia is new for everybody. Help to find bugs and patterns and idioms. What should be best practice? What should be avoided? What is confusing? What is missing? All this is the driver for innovation. If you are interested in this topic, the [Discussions](https://github.com/vknabel/lithia/discussions) section is your friend.
41+
42+
### Reporting Bugs
43+
44+
As every project and especially young projects, Lithia has bugs. But as Lithia is a programming language, it should be tested very thoroughly. If you find a bug, please report it in the [Issues](https://github.com/vknabel/lithia/issues/new) section. Please make sure to include a minimal example that reproduces the bug.
45+
46+
## Driving Evolution
47+
48+
Lithia is still in its early stages and it's still evolving and tries to find its way of getting things done.
49+
You don't have to start with a whole evolution proposal and a PR or even the implementation. Opening an [issue](https://github.com/vknabel/lithia/issues/new) or [discussion](https://github.com/vknabel/lithia/discussions) gets things going. You can also help to improve [existing proposals](https://github.com/vknabel/lithia/tree/main/proposals) or [drafts](https://github.com/vknabel/lithia/issues?q=label%3Aproposal).
50+
51+
### Writing Documentation
52+
53+
Currently the documentation is rough and currently only consists of the [README](README.md), the [proposals](./proposals/README.md), the [examples](./examples/) and generated [stdlib docs](./stdlib/README.md).
54+
What's missing are tutorials, guides and a reference. But also a website would be nice. If you are interested in this topic, open an [issue](https://github.com/vknabel/lithia/issues/new), [discussion](https://github.com/vknabel/lithia/discussions) or directly a pull request with your changes, e.g. if you found ~tpyos~ typos.
55+
56+
### Writing Code or Tests
57+
58+
Lithia is written in Go, uses Tree-Sitter for parsing, has an VSCode extension in Typescript and an embedded language server in Go. You could contribute to any of these topics and more. Details about the architecture can be found in the [Architecture](#architecture) section.
59+
60+
Lithia is tested with [Go's testing framework](https://golang.org/pkg/testing/) and [Tree-Sitter's testing framework](https://tree-sitter.github.io/tree-sitter/creating-parsers#testing-parsers). We use GitHub Actions to run the tests on every push and pull request. The [stdlib itself is tested](./stdlib/stdlib-tests.lithia) in Lithia.
61+
62+
### Reviewing Pull Requests
63+
64+
Nobody is perfect and code isn't either. Feel free to review pull requests and give feedback. If you don't understand specific changes, just ask. The issue might be the code or the documentation.
65+
66+
### Writing Libraries
67+
68+
If you wrote some code with Lithia, we'd like to link to it! Open a pull request with your changes to the [README](README.md) and we'll merge it. If you want to have some feedback and code review, head to the [Discussions](https://github.com/vknabel/lithia/discussions) and we will have a look at it.
69+
70+
## Architecture
71+
72+
Lithia consists of multiple projects:
73+
74+
- The grammar is written in [Tree-Sitter](https://tree-sitter.github.io/tree-sitter/) and lives in its own repository: [vknabel/tree-sitter-lithia](https://github.com/vknabel/tree-sitter-lithia).
75+
- The [VSCode extension](https://github.com/vknabel/vscode-lithia) is written in Typescript and lives in its own repository.
76+
- The core of Lithia is written in Go and lives in this repository.
77+
- The language server protocol implementation, which also lives in this repository.
78+
79+
### Development
80+
81+
We try to keep as much as possible within this repo and easy to install.
82+
This repository is structured as follows:
83+
84+
- The [parser](./parser/) is written in Go produces an Abstract Syntax Tree ([ast](./ast/)) from the Tree-Sitter output.
85+
- The interpreter is implemented in [runtime](./runtime/) and executes the AST.
86+
- Extensions to Lithia that are not part of the runtime core can be found in [external](./external/). They resemble the names of the standard library modules.
87+
- Most types and code is implemented in the [stdlib](./stdlib/). It is written in Lithia itself and is tested with the [stdlib-tests](./stdlib/stdlib-tests.lithia).
88+
- The language server is implemented in [langsrv](./langsrv/). It is the intelligent backend for the [VSCode extension](https://github.com/vknabel/vscode-lithia).
89+
90+
The easiest way to get started is using the devcontainer configured in this repository. It will install all dependencies and start a VSCode instance with the extension installed. You can then run the tests and debug the extension. The devcontainer is configured to run Lithia using `go run ./app/lithia`.
91+
So if you restart the vscode extension, window, devcontainer or the extension host, it will automatically recompile the lithia binary for you and you will get the latest language server implementation.
92+
93+
### Board
94+
95+
If you plan to contribute more frequently, we have a [GitHub project board](https://github.com/users/vknabel/projects/3/views/1) that contains all the issues and pull requests that are currently open.
96+
97+
The development of Lithia follows a brief concept and some rules. Don't take them too serious. We are pragmatic and do this as a hobby. They are mostly for myself.
98+
99+
**Sprints**
100+
101+
- provide a rough timespan
102+
- usually take 4 weeks
103+
- are not set in stone and can be changed
104+
- should result in at least one release
105+
106+
**Issues**
107+
108+
- are a `bug`, `docs`, `feature` or a `proposal`
109+
- features are assigned to an evolution proposal
110+
- are assigned to a sprint
111+
- have a status
112+
- **Backlog:** a new issue or an issue that could be tackled in theory.
113+
- **Upcoming:** this task is planned in the near future. Usually within this Sprint.
114+
- **In Progress:** the work for this task has already been started, but it has not been finished yet.
115+
- **Done:** every closed issue.
116+
117+
**Lithia Evolution proposals**
118+
119+
- drive the feature development of Lithia
120+
- are referenced by LE-xxx if they left the draft phase
121+
- serve as implementation guidance and documentation
122+
- might start with an `proposal` issue or a discussion in the forum
123+
- are open for everyone

0 commit comments

Comments
 (0)