mirror of
https://gitlab.com/openstapps/openstapps.git
synced 2026-03-08 07:42:34 +00:00
refactor: move logger to monorepo
This commit is contained in:
@@ -0,0 +1,25 @@
|
||||
# Branching model
|
||||
|
||||
## Possible branch names
|
||||
|
||||
* `master`
|
||||
* `develop`
|
||||
* `$ID-$TITLE`
|
||||
|
||||
### `master`
|
||||
|
||||
Current productive version of a project resides on the `master` branch.
|
||||
|
||||
### `develop`
|
||||
|
||||
The upcoming productive version - current development version - resides on the `develop` branch. The `develop` branch is unnecessary in smaller projects when the development is not too fast.
|
||||
|
||||
The `master` branch needs to be updated with a fast forward merge after every release in projects that have a `develop` branch.
|
||||
|
||||
### `$ID-$TITLE`
|
||||
|
||||
Development of features, bugfixes or refactoring is done in branches referencing an issue that follow the naming convention `$ID-$TITLE` where `$ID` is the number of the issue and `$TITLE` is the sluggified title of the issue. The [issues](ISSUES.md) integration of GitLab has a feature that creates such a branch and an accompanying merge request.
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Git - A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/)
|
||||
@@ -0,0 +1,21 @@
|
||||
# Coding style
|
||||
|
||||
These guidelines are meant for TypeScript based project but can be adapted for projects that are developed in other languages as well.
|
||||
|
||||
## Configuration
|
||||
|
||||
Consistent code structure and style is ensured by using [`@openstapps/configuration`](https://gitlab.com/openstapps/configuration). It contains configuration files for your editor, the TypeScript compiler and TSLint.
|
||||
|
||||
When you install this project and are missing any of the recommended configuration files, they will be automatically created for you.
|
||||
|
||||
## Comments
|
||||
|
||||
Plenty of inline comments should be used to make it easier to understand what the code is doing.
|
||||
|
||||
Inline comments should not explain what code from external projects is doing. Add missing documentation to those external projects.
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Commit guidelines](COMMITS.md)
|
||||
* [TypeScript coding guidelines](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines)
|
||||
* [Licensing guidelines](LICENSING.md)
|
||||
@@ -0,0 +1,60 @@
|
||||
# Commit guidelines
|
||||
|
||||
## Template
|
||||
|
||||
Commit subjects should match the following template:
|
||||
|
||||
> `TYPE`: `SUBJECT`
|
||||
>
|
||||
> `DESCRIPTION`
|
||||
|
||||
### `TYPE`
|
||||
|
||||
`TYPE` can have one of the following values:
|
||||
|
||||
| value | meaning |
|
||||
| --- | --- |
|
||||
| build | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
|
||||
| ci | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) |
|
||||
| docs | Documentation only changes |
|
||||
| feat | A new feature |
|
||||
| fix | A bug fix |
|
||||
| perf | A code change that improves performance |
|
||||
| refactor | A code change that neither fixes a bug nor adds a feature |
|
||||
| style | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
|
||||
| test | Adding missing tests or correcting existing tests |
|
||||
|
||||
These are the [types](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#type), that angular uses. They are easily adaptable for all TypeScript based web related projects.
|
||||
|
||||
### `SUBJECT`
|
||||
|
||||
`SUBJECT` should be written in the imperative mood. You can think of a short subject that completes a sentence that starts with "This commit will...".
|
||||
|
||||
The first line of the commit subject should not be longer than 50 chars overall.
|
||||
|
||||
### `DESCRIPTION`
|
||||
|
||||
`DESCRIPTION` can contain a longer description of the commit. Each line should not be longer than 70 chars. New lines can be used to structure the description.
|
||||
|
||||
To reference or close [issues](ISSUES.md) GitLab [keywords](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html) can be used in the last line(s) of the description:
|
||||
|
||||
> Fixes #42
|
||||
|
||||
or
|
||||
|
||||
> References #42
|
||||
|
||||
## Advantages
|
||||
|
||||
The result of those commit guidelines is a concise and clear history of the development.
|
||||
|
||||
Another advantage is the automatic [generation](https://www.npmjs.com/package/conventional-changelog-cli) of a changelog that gives an overview of the changes.
|
||||
|
||||
```shell
|
||||
conventional-changelog -p angular -i CHANGELOG.md -s -r 0
|
||||
```
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Recommendations on commit messages](https://chris.beams.io/posts/git-commit/)
|
||||
* [Versioning](VERSIONING.md)
|
||||
@@ -0,0 +1,84 @@
|
||||
# Documentation
|
||||
|
||||
Every projects need a `README.md` as a standardized entry of information about the scope of a [project](PROJECT.md) and how to install and execute it.
|
||||
|
||||
## Inline (code) documentation
|
||||
|
||||
Code is annotated with [TypeDoc](https://typedoc.org/), which then can be used to generate complete documentations of the API of the code.
|
||||
|
||||
### Guidelines
|
||||
|
||||
Please follow these guidelines to reduce redundance:
|
||||
|
||||
* The purpose of inline documentation is to explain what the line of code actually does without explaining syntax or external references. Example:
|
||||
|
||||
```typescript
|
||||
// extend the template by the properties of the base template
|
||||
templateBase.properties = mergeObjects(
|
||||
templateBase.properties,
|
||||
templates['base.template.json'].mappings._default_.properties
|
||||
);
|
||||
```
|
||||
|
||||
* Follow the [recommendations](http://typedoc.org/guides/doccomments/) of `typedoc`, because it is used to generate documentation. Do not denote the types again in the documentation (`@param` and `@returns`), because they are already "documented" in the code itself. Example:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Gets a value from the storage using the provided key
|
||||
*
|
||||
* @param key Unique identifier of the wanted resource in storage
|
||||
*/
|
||||
async get<T>(key: string): Promise<T> {
|
||||
const entry = await this.storage.get(key);
|
||||
if (!entry) {
|
||||
throw new Error('Value not found.');
|
||||
}
|
||||
return entry;
|
||||
}
|
||||
```
|
||||
|
||||
### Inline Comments `//`
|
||||
|
||||
* Start inline comments with a lowercase letter and a space after the `//`
|
||||
* Place the comment above the line that it is referencing
|
||||
|
||||
```typescript
|
||||
// lorem ipsum
|
||||
const lorem;
|
||||
```
|
||||
|
||||
### Doc Comments `/**`
|
||||
|
||||
* Start with a capital letter
|
||||
* Keep the first line short
|
||||
* The first line should not end with a period, nor should it consist of multiple sentences
|
||||
* The first line should be easily scannable
|
||||
* If you want to comment more than one line, do a short summary in the first line, then continue after a blank line with the more detailed description
|
||||
* Document all parameters in functions using `@param`
|
||||
* `@param` must not contain a type annotation, just `@param name description`
|
||||
* Do not include `@return`, as it is redundant information
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Short summary of the function, without a period
|
||||
*
|
||||
* This is a very long description, that could never possibly fit on one line, nor could it
|
||||
* be read in a short amount of time. Because we can use multiple sentences here, we can actually
|
||||
* use a period.
|
||||
*
|
||||
* @param foo This parameter does something
|
||||
*/
|
||||
function fun(foo: number): Foo {
|
||||
```
|
||||
|
||||
## `CONTRIBUTING.md`
|
||||
|
||||
Every project can have a `CONTRIBUTING.md` which explains how to contribute to the project either just by issues or code contributions.
|
||||
|
||||
## Issue templates
|
||||
|
||||
The path `.gitlab/issue_templates` can contain markdown files which act as templates for issues. These are available as an options during issue creation and just have to be filled by the creator of the issue. They act as orientation which information need sto be provided.
|
||||
|
||||
## Further resources
|
||||
|
||||
* [GitLab issue templates](https://gitlab.com/help/user/project/description_templates.md)
|
||||
@@ -0,0 +1,9 @@
|
||||
# Issues
|
||||
|
||||
Regardless of scope - bug, feature, discussion - technical or organisational - everything is an issue.
|
||||
|
||||
Issues keep a discussion of the topic, are related to a [branch](BRANCHING.md), keep track of the progress, link to related issues and streamline the process of development.
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Always start with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/)
|
||||
@@ -0,0 +1,48 @@
|
||||
# Licensing guidelines
|
||||
|
||||
This and affiliated projects are licensed under GPLv3 or APGLv3, if not stated otherwise.
|
||||
|
||||
## Licensing projects
|
||||
|
||||
Copy the license from [projectmanagement](../../LICENSE) or the [official standalone](https://www.gnu.org/licenses/gpl-3.0-standalone.html) (with the filename `LICENSE`) into the root of your project.
|
||||
|
||||
## The GPL copyright notice
|
||||
|
||||
According to the GPLv3 guidelines for [adding the license to a new program](http://www.gnu.org/licenses/gpl-3.0-standalone.html#howto) a license note should be added at the beginning of each source file.
|
||||
|
||||
```typescript
|
||||
/*
|
||||
* Copyright (C) <year> StApps
|
||||
* This program is free software: you can redistribute it and/or modify it
|
||||
* under the terms of the GNU General Public License as published by the Free
|
||||
* Software Foundation, version 3.
|
||||
*
|
||||
* This program is distributed in the hope that it will be useful, but WITHOUT
|
||||
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
||||
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
|
||||
* more details.
|
||||
*
|
||||
* You should have received a copy of the GNU General Public License along with
|
||||
* this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
*/
|
||||
```
|
||||
|
||||
### New Files
|
||||
|
||||
The `<year>` should be inserted with the current year. E.g.:
|
||||
|
||||
```typescript
|
||||
* Copyright (C) 2019 StApps
|
||||
```
|
||||
|
||||
### Updating Files
|
||||
|
||||
If the file is updated in a new year after its creation, the `<year>` should be appended as a comma seperated list with spaces in between. E.g.:
|
||||
|
||||
```typescript
|
||||
* Copyright (C) 2018, 2019, 2021 StApps
|
||||
```
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Coding style](CODING.md)
|
||||
@@ -0,0 +1,14 @@
|
||||
# Merging & merge requests
|
||||
|
||||
Once development of an [issue](ISSUES.md) on a [branch](BRANCHING.md) is completed the merge request becomes relevant. It also can be used during development for continuous reviews and iterative improvements.
|
||||
|
||||
A merge request can also gather the work of multiple issues.
|
||||
|
||||
Merge requests are used to merge the changes to the main branches (`master`, `develop`). Every merge request needs to be reviewed/commented by at least 2 other developers before they can be accepted. This ensure that all guidelines are followed and that the scope of the issue is matched.
|
||||
|
||||
Before any merge of an `issue`-branch into the according `master`-branch, the commits of the `issue`-branch shall be tidied up.
|
||||
Unstage your commits from the `issue`-branch (`git reset master`). Create your new commit(s) and push them to the remote repository (`git push --force`).
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Commits](COMMITS.md)
|
||||
@@ -0,0 +1,37 @@
|
||||
# Project
|
||||
|
||||
A project is an entity that solves a specific task.
|
||||
|
||||
Abstractable components of multiple projects should be extracted into another new project.
|
||||
|
||||
Node.js projects are published on NPMjs.com in the `@openstapps` group.
|
||||
|
||||
## Structure
|
||||
|
||||
Node.js/TypeScript based projects should employ the following structure:
|
||||
|
||||
```
|
||||
src/ Sources
|
||||
test/ Test files
|
||||
lib/ Compiled sources
|
||||
cli.js cli tool
|
||||
index.js API (classes, function, constants, ...)
|
||||
index.d.ts TypeScript definitions for API
|
||||
.editorconfig
|
||||
.gitignore List of files that should be ignored by git
|
||||
.npmignore List of files that should be ignored by npm
|
||||
package.json Package description
|
||||
package-lock.json Meta file, that fixates dependencies
|
||||
README.md Description of project, entry point for documentation
|
||||
tsconfig.json TypeScript configuration
|
||||
tslint.json TSLint configuration
|
||||
```
|
||||
|
||||
### `@openstapps/configuration`
|
||||
|
||||
For the contents and purpose of `.editorconfig`, `tsconfig.json` and `tslint.json` refer to `@openstapps/configuration`.
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Coding style](CODING.md)
|
||||
* [Versioning](VERSIONING.md)
|
||||
@@ -0,0 +1,37 @@
|
||||
# Publishing
|
||||
|
||||
## NPM
|
||||
|
||||
All projects that use the [OpenStApps configuration](https://gitlab.com/openstapps/configuration) and implement the automatic publishing via GitLab CI can simply be published to the NPM registry by using the appropriate job. It uses the `NPM_AUTH_TOKEN` that is a [protected variable](https://gitlab.com/groups/openstapps/-/settings/ci_cd) of the OpenStApps group. To trigger this job, a new tag has to be created (on the master branch):
|
||||
|
||||
### Use current [master branch](BRANCHING.md)
|
||||
|
||||
```shell
|
||||
git checkout master
|
||||
git pull
|
||||
```
|
||||
|
||||
### Update [version](VERSIONING.md)
|
||||
|
||||
```shell
|
||||
npm version (major|minor|patch)
|
||||
```
|
||||
|
||||
After these steps there should 2 new commits:
|
||||
|
||||
* A version commit
|
||||
* A changelog commit
|
||||
|
||||
Also a new git tag should be created.
|
||||
|
||||
**CAUTION: Make sure that everything was successful, before running the next command, that pushes commits to GitLab!**
|
||||
|
||||
### Pushing commits and version tag created in previous step
|
||||
|
||||
To push the previously created commits and version tag you can use the following convenience script:
|
||||
|
||||
```shell
|
||||
npm run push
|
||||
```
|
||||
|
||||
After you've pushed the commits and tags a pipeline will be started for the tag that includes a job that will automatically publish a new package to the NPM registry.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Versioning guidelines
|
||||
|
||||
We use semantic version through `npm`.
|
||||
|
||||
* `npm version patch`: For fixes/patches
|
||||
* `npm version minor`: For new features
|
||||
* `npm version major`: For breaking changes in the API
|
||||
|
||||
Or directly with `git tag vMAJOR.MINOR.PATCH`.
|
||||
|
||||
This tag is set on the `develop`- (if present) or on the `master`-[branch](BRANCHING.md).
|
||||
|
||||
## Further resources
|
||||
|
||||
* [Commit guidelines](COMMITS.md)
|
||||
Reference in New Issue
Block a user