mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2025-12-30 17:00:57 -06:00
chore: tidy general-info docs
This commit is contained in:
Phil Davis
@@ -20,11 +20,11 @@ Translations are automatically synced on a daily basis in the night.
|
||||
|
||||
## Implementing ocis Translations
|
||||
|
||||
The implementation example is a guide and shall show how to do it. You can derive at any time according your needs.
|
||||
The implementation example is a guide and shall show how to do it. You can derive at any time according to your needs.
|
||||
|
||||
Note that paths are examples and can be adapted based on requirements.\
|
||||
Replace `<service-name>` with the name of the respective service.\
|
||||
Translations have a `context` and a `translatable string`. The context is shown on Transifex but not translated and helps translators to get a context for the string to be translated.
|
||||
Translations have a `context` and a `translatable string`. The context is shown on Transifex but not translated and helps translators to get a context for the string to be translated.
|
||||
|
||||
* Add the `OCIS_DEFAULT_LANGUAGE` envvar in `services/<service-name>/pkg/config/config.go`.\
|
||||
For details see the userlog or notifications service code.
|
||||
@@ -50,7 +50,7 @@ Translations have a `context` and a `translatable string`. The context is shown
|
||||
var yourString = l10n.Template("Translation String")
|
||||
```
|
||||
|
||||
* In the `Makefile` in the **ocis root**, add in the following section the service you want to synchroize translations with Transifex:
|
||||
* In the `Makefile` in the **ocis root**, add in the following section the service you want to synchronize translations with Transifex:
|
||||
```
|
||||
# add a service here when it uses transifex
|
||||
L10N_MODULES := \
|
||||
@@ -61,7 +61,7 @@ Translations have a `context` and a `translatable string`. The context is shown
|
||||
```
|
||||
|
||||
* In the `Makefile` of the **`<service-name>`** add:\
|
||||
_At the beginnig:_
|
||||
_At the beginning:_
|
||||
```
|
||||
# Where to write the files generated by this makefile.
|
||||
OUTPUT_DIR = ./pkg/service/<...>/l10n
|
||||
|
||||
@@ -8,7 +8,7 @@ geekdocFilePath: envvar-scopes.md
|
||||
geekdocCollapseSection: true
|
||||
---
|
||||
|
||||
The scope of an environment variable can be derived from its name. Therefore it is important to follow the correct naming scheme to enable easy and proper identification. This is important when either:
|
||||
The scope of an environment variable can be derived from its name. Therefore, it is important to follow the correct naming scheme to enable easy and proper identification. This is important when either:
|
||||
|
||||
- a new local envvar is introduced.
|
||||
- a new global envvar is added to an existing local envvar.
|
||||
@@ -24,7 +24,7 @@ The scope of an environment variable can be derived from its name. Therefore it
|
||||
|
||||
### Local Envvars
|
||||
|
||||
A local envvar always starts with the the service name like `POSTPROCESSING_LOG_FILE`.
|
||||
A local envvar always starts with the service name like `POSTPROCESSING_LOG_FILE`.
|
||||
|
||||
### Global Envvars
|
||||
|
||||
@@ -36,7 +36,7 @@ To get a list of global envvars used in all services, see the [Global Environmen
|
||||
|
||||
### Lifecycle
|
||||
|
||||
In the struct tag values of our config data types, we are using three key/value pairs to document the lifecycle of a config variable: `introductionVersion`, `deprecationVersion` and `removalVersion`. During the development cycle, a new value should set to `%%NEXT%%` as long as no release is scheduled. During the release process, the palceholder will be replaced with the actual version number. Our docs helper scripts will then automatically generate the correct documentation based on the version number.
|
||||
In the struct tag values of our config data types, we are using three key/value pairs to document the lifecycle of a config variable: `introductionVersion`, `deprecationVersion` and `removalVersion`. During the development cycle, a new value should set to `%%NEXT%%` as long as no release is scheduled. During the release process, the placeholder will be replaced with the actual version number. Our docs helper scripts will then automatically generate the correct documentation based on the version number.
|
||||
|
||||
## Deprecations
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ geekdocFilePath: new-service-checklist.md
|
||||
geekdocCollapseSection: true
|
||||
---
|
||||
|
||||
When a new service gets introduced, this checklist is a good startingpoint for things that need to be completed before the service gets published (merged). This list is without claim of completeness or correct sort order.
|
||||
When a new service gets introduced, this checklist is a good starting point for things that need to be completed before the service gets published (merged). This list is without claim of completeness or correct sort order.
|
||||
|
||||
## New Service Checklist
|
||||
|
||||
@@ -20,9 +20,9 @@ Use this checklist with copy/paste in your PR - right from the beginning. It ren
|
||||
- [ ] For images and example files used in README.md:
|
||||
- Create a folder named `md-sources` on the same level where README.md is located. Put all the images and example files referenced by README.md into this folder.
|
||||
- Use absolute references like `https://raw.githubusercontent.com/owncloud/ocis/master/services/<service-name>/md-sources/file` to make the content accessible for both README.md and owncloud.dev
|
||||
bad `<img src="https://github.com/owncloud/ocis/blob/master/services/graph/images/mermaid-graph.svg" width="500" />`
|
||||
bad `<img src="https://github.com/owncloud/ocis/blob/master/services/graph/images/mermaid-graph.svg" width="500" />`
|
||||
good `<img src="https://raw.githubusercontent.com/owncloud/ocis/master/services/graph/images/mermaid-graph.svg" width="500" />`
|
||||
- [ ] If new CLI command are introduced, that command must be described in the README.md.
|
||||
- [ ] If new CLI commands are introduced, those commands must be described in the README.md.
|
||||
- [ ] If new global envvars are introduced, the name must start with `OCIS_`.
|
||||
- [ ] Add the service to the makefile in the ocis repo root.
|
||||
- [ ] Make the service startable for binary and individual startup:
|
||||
@@ -35,12 +35,12 @@ Use this checklist with copy/paste in your PR - right from the beginning. It ren
|
||||
- The description must reflect the behaviour AND usually has a positive code quality impact.
|
||||
- [ ] Create proper description strings for envvars - see other services for examples, especially when it comes to multiple values. This must include:
|
||||
- base description, set of available values, description of each value.
|
||||
- [ ] When suggestable commits are created for text changes and you agree, collect them to a batch and commit them. Do not forget to rebase locally to avoid overwriting the changes made.
|
||||
- [ ] When suggested commits are created for text changes, and you agree, collect them to a batch and commit them. Do not forget to rebase locally to avoid overwriting the changes made.
|
||||
- [ ] If new envvars are introduced which serve the same purpose but in multiple services, an additional envvar must be added at the beginning of the list starting with `OCIS_` (global envvar).
|
||||
- [ ] Ensure that a service has a debug port
|
||||
- [ ] If the new service introduces a new port:
|
||||
- The port must be added to [port-ranges.md](https://github.com/owncloud/ocis/blob/master/docs/services/general-info/port-ranges.md) and to the README.md file.
|
||||
- [ ] Make sure to have a function `FullDefaultConfig()` in `pkg/config/defaults/defaultconfig.go` of your service. It is needed to create the documentation.
|
||||
- [ ] Add metrics to the code to enable monitoring. See the proxy service for implementation details.
|
||||
- Plus add a monitoring documentation in the README.md file
|
||||
- Plus add documentation about monitoring in the README.md file
|
||||
```
|
||||
|
||||
@@ -8,7 +8,7 @@ geekdocFilePath: port-ranges.md
|
||||
geekdocCollapseSection: true
|
||||
---
|
||||
|
||||
oCIS services often need a port to expose their services to other services or the outside world. As users may have many different extensions running on the same machine, we should track port usage in the oCIS ecosystem. In the best case we ensure that each extension uses a non colliding port range, to make life of users easier.
|
||||
oCIS services often need a port to expose their services to other services or the outside world. As users may have many different extensions running on the same machine, we should track port usage in the oCIS ecosystem. In the best case, we ensure that each extension uses a non-colliding port range, to make life easier for users.
|
||||
|
||||
This page tracks the knowingly used port ranges.
|
||||
|
||||
@@ -16,7 +16,7 @@ Feel free to "reserve" a free port range when you're developing an extension by
|
||||
|
||||
If you're developing a non-public extension, we recommend using ports outside of the ranges listed below.
|
||||
|
||||
We also suggest to use the last port in your extensions' range as a debug/metrics port.
|
||||
We also suggest using the last port in your extensions' range as a debug/metrics port.
|
||||
|
||||
## Allocations
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ The type of registry to use can be configured with the `MICRO_REGISTRY` environm
|
||||
|
||||
### `memory`
|
||||
|
||||
Setting the environment variable to `memory` starts an inmemory registry. This only works with the single binary deployment.
|
||||
Setting the environment variable to `memory` starts an in-memory registry. This only works with the single binary deployment.
|
||||
|
||||
### `nats-js-kv` (Default)
|
||||
|
||||
@@ -25,15 +25,15 @@ Set the environment variable to `nats-js-kv` or leave it empty to use a nats-js
|
||||
- Optional: Use `MICRO_REGISTRY_AUTH_USERNAME` and `MICRO_REGISTRY_AUTH_PASSWORD` to authenticate with the nats cluster.
|
||||
### `kubernetes`
|
||||
|
||||
When deploying in a kubernetes cluster, the kubernetes registry can be used. Additionally the `MICRO_REGISTRY_ADDRESS` environment
|
||||
When deploying in a kubernetes cluster, the kubernetes registry can be used. Additionally, the `MICRO_REGISTRY_ADDRESS` environment
|
||||
variable needs to be set to the url of the kubernetes registry.
|
||||
|
||||
### Deprecated Registries
|
||||
|
||||
These registries are currently working but will be removed in a later version. It is recommended to switch to a supported one.
|
||||
|
||||
- `nats`. Uses a registry based on nats streams. Requires `MICRO_REGISTRY_ADDRESS` to bet set.
|
||||
- `etcd`. Uses an etcd cluster as registry. Requires `MICRO_REGISTRY_ADDRESS` to bet set.
|
||||
- `consul`. Uses `HashiCorp Consul` as registry. Requires `MICRO_REGISTRY_ADDRESS` to bet set.
|
||||
- `nats`. Uses a registry based on nats streams. Requires `MICRO_REGISTRY_ADDRESS` to be set.
|
||||
- `etcd`. Uses an etcd cluster as the registry. Requires `MICRO_REGISTRY_ADDRESS` to be set.
|
||||
- `consul`. Uses `HashiCorp Consul` as registry. Requires `MICRO_REGISTRY_ADDRESS` to be set.
|
||||
- `mdns`. Uses multicast dns for registration. This type can have unwanted side effects when other devices in the local network use mdns too.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user