Skip to content

Commit ae65852

Browse files
SchneegansSchneegans
committed
📝 Add some content
1 parent da61672 commit ae65852

File tree

11 files changed

+432
-11
lines changed

11 files changed

+432
-11
lines changed

‎astro.config.mjs‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,17 @@ export default defineConfig({
2222
},
2323
sidebar: [
2424
{
25-
label: 'Getting Started',
26-
autogenerate: { directory: 'getting-started' },
25+
label: 'Usage Guide',
26+
items: ['usage/intro', 'usage/citing', 'usage/migration-guide'],
2727
},
2828
{
29-
label: 'Getting Involved',
30-
autogenerate: { directory: 'getting-involved' },
29+
label: 'Development',
30+
items: [
31+
'development/architecture',
32+
'development/contribution-guide',
33+
'development/continuous-integration',
34+
'development/release-management',
35+
],
3136
},
3237
{
3338
label: 'Plugins',

‎src/assets/architecture.svg‎

Lines changed: 73 additions & 0 deletions
Loading

‎src/content/docs/development/architecture.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Architecture
3+
description: The architecture of CosmoScout VR.
4+
tableOfContents: false
5+
---
6+
7+
The high-level architecture of CosmoScout VR is shown in the diagram below.
8+
More fine-grained information on the specific plugins is available in the documentation of each plugin.
9+
10+
![CosmoScout VR Architecture](/src/assets/architecture.svg)
11+
12+
As a user, you will get in touch with the `cosmoscout` executable and the individual plugin libraries.
13+
While the plugins may link to some special-purpose third-party libraries, all of them link against the CosmoScout VR core libraries.
14+
15+
There are five core libraries: [`cs-core`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-core) contains all the application logic and links against [`cs-graphics`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-graphics), [`cs-gui`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-gui) and [`cs-scene`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-scene).
16+
All of them use some utility functionality from [`cs-utils`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-utils).
17+
18+
CosmoScout VR uses [several third-party libraries](https://github.com/cosmoscout/cosmoscout-vr/blob/main/docs/dependencies.md) as a basis.
19+
The most important ones are [ViSTA](https://github.com/cosmoscout/vista) (which itself requires [OpenSG 1.8](https://github.com/cosmoscout/opensg-1.8)) and [SPICE](https://naif.jpl.nasa.gov/naif/toolkit.html).

‎src/content/docs/development/continuous-integration.mdx‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Continuous Integration
3+
description: Learn how CosmoScout VR uses Github Actions for continuous integration.
4+
---
5+
6+
[Github Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) is used for continuous integration of CosmoScout VR.
7+
The file [`build.yml`](https://github.com/cosmoscout/cosmoscout-vr/blob/main/.github/workflows/build.yml) describes which jobs are run whenever a commit is pushed or a pull request is opened.
8+
9+
## Clang-Format Check
10+
We enforce specific code formatting rules described in the file [`.clang-format`](https://github.com/cosmoscout/cosmoscout-vr/blob/main/.clang-format).
11+
For each and **every push event**, a job is executed which checks whether the code base obeys these rules.
12+
13+
Commits passing this check will be marked with a ✔️, when the style does not match the rules, the commit will receive a ❌.
14+
15+
## Comment Percentage Check
16+
For **pull requests only**, a job is run which analyses the amount of comments in the source tree.
17+
Therefore the percentage of source lines of code containing comments is calculated with the script [`cloc.sh`](https://github.com/cosmoscout/cosmoscout-vr/blob/main/tools/cloc.sh) and compared with the amount of comments in the base branch.
18+
19+
This test will pass if the amount of comments did not decrease.
20+
21+
## Builds of CosmoScout VR
22+
[Github Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) is also used to compile the code of CosmoScout VR and all of its dependencies.
23+
As this job takes quite some time, it is only executed for the events below:
24+
* For each push to `main` if the commit message does not contain `[no-ci]`.
25+
* For each push to any branch if commit message contains `[run-ci]`.
26+
* For pull requests.
27+
28+
The code is compiled on Ubuntu (with GCC and Clang) and on Windows (with MSVC).
29+
Tests are executed on all platforms and the results are uploaded to [coveralls.io](https://coveralls.io/github/cosmoscout/cosmoscout-vr).
30+
31+
Both, the externals and CosmoScout's code itself is built with [ccache](https://ccache.dev/) and [clcache](https://github.com/frerich/clcache) in order to speed up build times by a factor of five.
32+
Between job runs, the object file cache is stored with the [cache action](https://github.com/actions/cache).
33+
34+
## Unit Tests
35+
36+
In CosmoScout VR, unit testing is done with [doctest](https://github.com/onqtam/doctest).
37+
Tests are executed for every build, so the same behavior of `[no-ci]` and `[run-ci]` as above applies here.
38+
There are two types of test cases, _regular_ tests and _graphical_ tests.
39+
40+
### Regular Tests
41+
42+
Regular tests require no OpenGL and no window.
43+
You can run them with the following scripts.
44+
45+
#### Linux:
46+
47+
```shell
48+
./install/linux-Release/bin/run_tests.sh
49+
```
50+
51+
#### Windows:
52+
```batch
53+
install\windows-Release\bin\run_tests.bat
54+
```
55+
56+
### Graphical Tests
57+
58+
These tests require an OpenGL context and will open a window.
59+
Oftentimes they capture a screenshot and compare the result to a reference image.
60+
61+
In order to make them possible even if there is no graphics card or display attached, they require [Xvfb](https://en.wikipedia.org/wiki/Xvfb) and [imagemagick](https://imagemagick.org/index.php) to be installed on your system.
62+
Graphical tests can only be executed on Linux for now:
63+
64+
```shell
65+
./install/linux-Release/bin/run_graphical_tests.sh
66+
```

‎src/content/docs/development/contribution-guide.mdx‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Write Code for CosmoScout VR
3+
description: Some guidelines for contributing to CosmoScout VR
4+
---
5+
6+
Whenever you encounter a 🪲 **bug** or have 🎉 **feature request**,
7+
report this via [Github issues](https://github.com/cosmoscout/cosmoscout-vr/issues).
8+
9+
We are happy to receive contributions to CosmoScout VR in the form of **pull requests** via Github.
10+
Feel free to fork the repository, implement your changes and create a merge request to the `main` branch.
11+
There is a [forking guide](#forking-cosmoscout-vr) available to get you started!
12+
13+
## Branching Guidelines
14+
15+
New features and bug fixes are implemented in `feature/*` branches and are merged to `main` once they are finished.
16+
When a milestone is reached, a new tag is created.
17+
18+
:::tip
19+
[Github Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) are used for continuous integration.
20+
All pull requests and pushes to `main` are built automatically.
21+
If you want to test a specific commit on any other branch, add **`[run-ci]`** to your commit message.
22+
:::
23+
24+
## Coding Guidelines
25+
26+
* Each header file should contain an include guard. For CosmoScout VR classes the naming scheme should be `CS_{NAMESPACE}_{FILNAME}_HPP` and for plugins it should be `CSP_{PLUGIN}_{FILNAME}_HPP`.
27+
* Class names should be written in CamelCase (e.g. `MyClass`).
28+
* Class methods should be written in small camelCase (e.g. `doSomething()`).
29+
* Class members should start with a small `m` and continue in CamelCase (e.g. `mMyClassMember`).
30+
* Apply clang-format before you create a merge request (either setup your IDE to do this or use the `clang-format.sh` script)
31+
* Never use `using namespace`.
32+
* Use features of modern C++11 / C++14 / C++17 (e.g. range-based for-loops, std::optional, std::variant, ...)!
33+
34+
### Git Commit Messages
35+
36+
Commits should start with a Capital letter and should be written in present tense (e.g. __:tada: Add cool new feature__ instead of __:tada: Added cool new feature__).
37+
It's a great idea to start the commit message with an applicable emoji. This does not only look great but also makes you rethink what to add to a commit.
38+
* 🎉 `:tada:` when when adding a cool new feature
39+
* 🔧 `:wrench:` when refactoring / improving a small piece of code
40+
* 🔨 `:hammer:` when refactoring / improving large parts of the code
41+
* ✨ `:sparkles:` when applying clang-format
42+
* 🎨 `:art:` improving / adding assets like textures or 3D-models
43+
* 🚀 `:rocket:` when improving performance
44+
* 📝 `:memo:` when writing docs
45+
* 🪲 `:beetle:` when fixing a bug
46+
* 💚 `:green_heart:` when fixing the CI build
47+
* ✔️ `:heavy_check_mark:` when working on tests
48+
* 🔼 `:arrow_up_small:` when adding / upgrading dependencies
49+
* 🔽 `:arrow_down_small:` when removing / downgrading dependencies
50+
* 🔀 `:twisted_rightwards_arrows:` when merging branches
51+
* 🔥 `:fire:` when removing files
52+
* 🚚 `:truck:` when moving / renaming files or namespaces
53+
54+
:::tip
55+
A good way to enforce this on your side is to use a `commit-hook`. To do this, paste the following script into `.git/hooks/commit-msg`.
56+
57+
```bash title=".git/hooks/commit-msg"
58+
#!/bin/bash
59+
60+
# regex to validate in commit msg
61+
commit_regex='(:(tada|wrench|hammer|sparkles|art|rocket|memo|beetle|green_heart|arrow_up_small|arrow_down_small|twisted_rightwards_arrows|fire|truck|heavy_check_mark):(.+))'
62+
error_msg="Aborting commit. Your commit message is missing an emoji as described in CONTRIBUTING.md"
63+
64+
if ! grep -xqE "$commit_regex" "$1"; then
65+
echo "$error_msg" >&2
66+
exit 1
67+
fi
68+
```
69+
70+
And make sure that it is executable:
71+
72+
``` bash
73+
chmod +x .git/hooks/commit-msg
74+
```
75+
:::
76+
77+
# Forking CosmoScout VR
78+
79+
This is pretty straight-forward. Just click the **Fork** button on the top right of this page. Then clone the forked repository, perform your changes, push to a feature branch and create a pull request to CosmoScout's `main` branch.
80+
81+
``` bash
82+
git clone [email protected]:<your user name>/cosmoscout-vr.git
83+
cd cosmoscout-vr
84+
git remote add upstream [email protected]:cosmoscout/cosmoscout-vr.git
85+
git checkout main
86+
git submodule update --init --recursive
87+
git checkout -b feature/your-new-feature
88+
89+
# ... do and commit your changes!
90+
91+
git push origin feature/your-new-feature
92+
```
93+
94+
When there were changes in CosmoScout's `main` branch, you will need to merge those to your fork before creating a pull request:
95+
96+
``` bash
97+
git fetch upstream
98+
git merge upstream/main
99+
```
100+
101+
Then you can create a pull request on GitHub to CosmoScout's `main` branch.
102+
103+
## Creating a new plugin
104+
105+
From a git-perspective, this is pretty straight-forward.
106+
All you need to do is creating a new directory in `plugins/`.
107+
For the beginning, you can copy the contents of another similar plugin to that directory.
108+
It will be picked up automatically by the build system.
109+
110+
:::tip
111+
The new directory will also be ignored by git (due to the toplevel `.gitignore` file).
112+
That means that you can use a git repository for your plugin.
113+
:::

‎src/content/docs/development/release-management.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: Release Management
3+
description: How releases are managed in CosmoScout VR.
4+
tableOfContents: false
5+
---
6+
7+
Releases are [published on GitHub](https://github.com/cosmoscout/cosmoscout-vr/releases).
8+
They are automatically created via [GitHub Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) whenever a git tag is pushed.
9+
The progress of future releases is tracked with [GitHub Milestones](https://github.com/cosmoscout/cosmoscout-vr/milestones).
10+
Submitted [issues](https://github.com/cosmoscout/cosmoscout-vr/issues) will be assigned to a specific release (depending on their importance and complexity).
11+
12+
[GitHub Projects](https://github.com/cosmoscout/cosmoscout-vr/projects) will be used for high-level planning of complex features, such as network synchronization or photorealistic HDR rendering.
13+
14+
## Version Numbers
15+
16+
Releases in the 1.x.x series will most likely have a lot of breaking API changes, as the software becomes more and more mature.
17+
However, starting from version 2.0.0, version numbers of CosmoScout VR will be assigned according to the [Semantic Versioning](https://semver.org/) scheme.
18+
This means, given a version number MAJOR.MINOR.PATCH, we will increment the:
19+
20+
1. MAJOR version when we make incompatible API changes,
21+
2. MINOR version when we add functionality in a backwards compatible manner, and
22+
3. PATCH version when we make backwards compatible bug fixes.
23+
24+
## Creating Releases
25+
26+
When a new version of CosmoScout VR is released, the following steps are performed.
27+
28+
```bash
29+
git checkout main
30+
git submodule update --init --recursive
31+
```
32+
33+
First, the [changelog.md](https://github.com/cosmoscout/cosmoscout-vr/blob/main/docs/changelog.md) has to be updated.
34+
Based on the commits since the last release and the completed milestone, a list of changes is compiled.
35+
When this is done, the file has to be comitted:
36+
37+
```bash
38+
git add docs/changelog.md
39+
git commit -m ":memo: Update changelog.md"
40+
```
41+
42+
Then edit the [project(... VERSION ...)](https://github.com/cosmoscout/cosmoscout-vr/blob/main/CMakeLists.txt#L8) in the main `CMakeLists.txt` file according to the new version number.
43+
Afterwards, the change has to be comitted:
44+
45+
```bash
46+
git add CMakeLists.txt
47+
git commit -m ":tada: Bump version number"
48+
```
49+
50+
Then we create a new git tag and push this state to the `main` branch.
51+
52+
```bash
53+
git push origin main
54+
git tag v<new version number>
55+
git push origin v<new version number>
56+
```
57+
58+
The default downloads for tags on GitHub do not contain git submodules.
59+
Therefore, a separate archive containing all the submodule code is automatically created via [GitHub Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) when a tag is pushed.
60+
Furthermore, binaries for Windows and Linux are automatically compiled with [GitHub Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) and uploaded to the respective release.

‎src/content/docs/getting-involved/contribution-guide.mdx‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎src/content/docs/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ template: splash
55
hero:
66
actions:
77
- text: Read the Documentation
8-
link: /getting-started/intro/
8+
link: /usage/intro/
99
icon: right-arrow
1010
- text: Download from GitHub
1111
link: https://github.com/cosmoscout/cosmoscout-vr/releases

‎src/content/docs/usage/citing.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Citing CosmoScout VR
3+
description: How to cite CosmoScout VR in your work.
4+
tableOfContents: false
5+
---
6+
7+
If you use CosmoScout VR in your scientific work, please use the DOI of the version you are currently using.
8+
The DOI of each release is shown on the [releases page](https://github.com/cosmoscout/cosmoscout-vr/releases).
9+
10+
:::tip
11+
With the link below you can export a citation in many different formats.
12+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3381953.svg)](https://doi.org/10.5281/zenodo.3381953)
13+
:::
14+
15+
16+
## Papers
17+
18+
With the above DOI, you can cite the software itself. There are also a couple of related papers which you can refer to.
19+
20+
> S. Schneegans, M. Zeumer, J. Gilg, and A. Gerndt, **"CosmoScout VR: A Modular 3D Solar System Based on SPICE"**, 2022 IEEE Aerospace Conference (AERO), 2022. https://doi.org/10.1109/AERO53065.2022.9843488
21+
22+
> S. Schneegans, J. Gilg, V. Ahlers, and A. Gerndt, **"Real-Time Rendering of Eclipses without Incorporation of Atmospheric Effects"**, Computer Graphics Forum 41, 2022. https://doi.org/10.1111/cgf.14676
23+
24+
> S. Schneegans, T. Meyran, I. Ginkel, G. Zachmann, and A. Gerndt, **"Physically Based Real-Time Rendering of Atmospheres using Mie Theory"**. Computer Graphics Forum 43, 2024. https://doi.org/10.1111/cgf.15010
25+
26+
> J. Gilg, S. Zander, S. Schneegans, V. Ahlers, and A. Gerndt, "**Comparison of Depth Buffer Techniques for Large and Detailed 3D Scenes**", GI VR / AR Workshop, Gesellschaft für Informatik e.V., 2021. https://doi.org/10.18420/vrar2021_12
27+

‎src/content/docs/getting-started/intro.mdx‎ renamed to ‎src/content/docs/usage/intro.mdx‎

File renamed without changes.

0 commit comments

Comments
 (0)