-
Notifications
You must be signed in to change notification settings - Fork 41
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into release51
- Loading branch information
Showing
68 changed files
with
3,834 additions
and
66 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
22 changes: 22 additions & 0 deletions
22
packages/documentation/versioned_docs/version-1.50.0/about-sofie.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| --- | ||
| title: About Sofie | ||
| hide_table_of_contents: true | ||
| sidebar_label: About Sofie | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # NRK Sofie TV Automation System | ||
|
|
||
|  | ||
|
|
||
| _**Sofie**_ is a web-based TV automation system for studios and live shows, used in daily live TV news productions by the Norwegian public service broadcaster [**NRK**](https://www.nrk.no/about/) since September 2018. | ||
|
|
||
| ## Key Features | ||
|
|
||
| - User-friendly, modern web-based GUI | ||
| - State-based device control and playout of video, audio, and graphics | ||
| - Modular device-control architecture with support for several hardware \(and software\) setups | ||
| - Modular data-ingest architecture, supports MOS and Google spreadsheets | ||
| - Plug-in architecture for programming shows | ||
|
|
||
| _The NRK logo is a registered trademark of Norsk rikskringkasting AS. The license does not grant any right to use, in any way, any trademarks, service marks or logos of Norsk rikskringkasting AS._ |
8 changes: 8 additions & 0 deletions
8
...documentation/versioned_docs/version-1.50.0/for-developers/api-documentation.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| sidebar_position: 6 | ||
| --- | ||
|
|
||
| # API Documentation | ||
|
|
||
| The Sofie Blueprints API and the Sofie Peripherals API documentation is automatically generated and available through | ||
| [nrkno.github.io/sofie-core/typedoc](https://nrkno.github.io/sofie-core/typedoc). |
26 changes: 26 additions & 0 deletions
26
...ges/documentation/versioned_docs/version-1.50.0/for-developers/api-stability.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| --- | ||
| title: API Stability | ||
| sidebar_position: 11 | ||
| --- | ||
|
|
||
| Sofie has various APIs for talking between components, and for external systems to interact with. | ||
|
|
||
| We classify each api into one of two categories: | ||
|
|
||
| ## Stable | ||
|
|
||
| This is a collection of APIs which we intend to avoid introducing any breaking change to unless necessary. This is so external systems can rely on this API without needing to be updated in lockstep with Sofie, and hopefully will make sense to developers who are not familiar with Sofie's inner workings. | ||
|
|
||
| In version 1.50, a new REST API was introduced. This can be found at `/api/v1.0`, and is designed to allow an external system to interact with Sofie using simplified abstractions of Sofie internals. | ||
|
|
||
| The _Live Status Gateway_ is also part of this stable API, intended to allow for reactively retrieving data from Sofie. Internally it is translating the internal APIs into a stable version. | ||
|
|
||
| :::note | ||
| You can find the _Live Status Gateway_ in the `packages` folder of the [Sofie Core](https://github.com/nrkno/sofie-core) repository. | ||
| ::: | ||
|
|
||
| ## Internal | ||
|
|
||
| This covers everything we expose over DDP, the `/api/0` endpoint and any other http endpoints. | ||
|
|
||
| These are intended for use between components of Sofie, which should be updated together. The DDP api does have breaking changes in most releases. We use the `server-core-integration` library to manage these typings, and to ensure that compatible versions are used together. |
96 changes: 96 additions & 0 deletions
96
...ntation/versioned_docs/version-1.50.0/for-developers/contribution-guidelines.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| --- | ||
| description: >- | ||
| The Sofie team happily encourage contributions to the Sofie project, and | ||
| kindly ask you to observe these guidelines when doing so. | ||
| sidebar_position: 2 | ||
| --- | ||
|
|
||
| # Contribution Guidelines | ||
|
|
||
| ## About the Sofie TV Studio Automation Project | ||
|
|
||
| The Sofie project includes a number of open source applications and libraries developed and maintained by the Norwegian public service broadcaster, [NRK](https://www.nrk.no/about/). Sofie has been used to produce live shows at NRK since September 2018. | ||
|
|
||
| A list of the "Sofie repositories" [can be found here](libraries.md). NRK owns the copyright of the contents of the official Sofie repositories, including the source code, related files, as well as the Sofie logo. | ||
|
|
||
| The Sofie team at NRK is responsible for development and maintenance. We also do thorough testing of each release to avoid regressions in functionality and ensure interoperability with the various hardware and software involved. | ||
|
|
||
| The Sofie team welcomes open source contributions and will actively work towards enabling contributions to become mergeable into the Sofie repositories. However, as main stakeholder and maintainer we reserve the right to refuse any contributions. | ||
|
|
||
|
|
||
| ## About Contributions | ||
|
|
||
| Thank you for considering contributing to the Sofie project! | ||
|
|
||
| Before you start, there are a few things you should know: | ||
|
|
||
| ### “Discussions Before Pull Requests” | ||
|
|
||
| **Minor changes** (most bug fixes and small features) can be submitted directly as pull requests to the appropriate official repo. | ||
|
|
||
| However, Sofie is a big project with many differing users and use cases. **Larger changes** might be more difficult to merge into an official repository if NRK has not been made aware of their existence beforehand. To facilitate a timely handling of larger contributions, there’s a workflow intended to keep an open dialogue between all interested parties: | ||
|
|
||
| 1. Contributor opens an RFC (as a _GitHub issue_) in the appropriate repository. | ||
| 2. NRK evaluates the RFC, usually within a week. | ||
| 3. (If needed) NRK establishes contact with the RFC author, who will be invited to a workshop where the RFC is discussed. Meeting notes are published publicly on the RFC thread. | ||
| 4. The contributor references the RFC when a pull request is ready. | ||
|
|
||
| ### Base contributions on the in-development branch (or the master branch) | ||
| In order to facilitate merging, we ask that contributions are based on the latest (at the time of the pull request) _in-development_ branch (often named `release*`), alternatively the stable (eg. `master`) branch. NRK will take responsibility for rebasing stable contributions to the latest in-development branch if needed. | ||
| See **CONTRIBUTING.md** in each official repository for details on which branch to use as a base for contributions. | ||
|
|
||
| ## Developer Guidelines | ||
|
|
||
| ### Pull Requests | ||
|
|
||
| We encourage you to open PRs early! If it’s still in development, open the PR as a draft. | ||
|
|
||
| ### Types | ||
|
|
||
| All official Sofie repositories use TypeScript. When you contribute code, be sure to keep it as strictly typed as possible. | ||
|
|
||
| ### Code Style & Formatting | ||
|
|
||
| Most of the projects use a linter (eslint) and a formatter (prettier). Before submitting a pull request, please make sure it conforms to the linting rules by running yarn lint. yarn lint --fix can fix most of the issues. | ||
|
|
||
| ### Documentation | ||
|
|
||
| We rely on two types of documentation; the [Sofie documentation](https://nrkno.github.io/sofie-core/) ([source code](https://github.com/nrkno/sofie-core/tree/master/packages/documentation)) and inline code documentation. | ||
|
|
||
| We don't aim to have the "absolute perfect documentation possible", BUT we do try to improve and add documentation to have a good-enough-to-be-comprehensible standard. We think that: | ||
|
|
||
| * _What_ something does is not as important – we can read the code for that. | ||
| * _Why_ something does something, **is** important. Implied usage, side-effects, descriptions of the context etcetera... | ||
|
|
||
| When you contribute, we ask you to also update any documentation where needed. | ||
|
|
||
| ### Updating Dependencies | ||
| When updating dependencies in a library, it is preferred to do so via `yarn upgrade-interactive --latest` whenever possible. This is so that the versions in `package.json` are also updated as we have no guarantee that the library will work with versions lower than that used in the `yarn.lock` file, even if it is compatible with the semver range in `package.json`. After this, a `yarn upgrade` can be used to update any child dependencies | ||
|
|
||
| Be careful when bumping across major versions. | ||
|
|
||
| Also, each of the libraries has a minimum nodejs version specified in their package.json. Care must be taken when updating dependencies to ensure its compatibility is retained. | ||
|
|
||
| ### Resolutions | ||
|
|
||
| We sometimes use the `yarn resolutions` property in `package.json` to fix security vulnerabilities in dependencies of libraries that haven't released a fix yet. If adding a new one, try to make it as specific as possible to ensure it doesn't have unintended side effects. | ||
|
|
||
| When updating other dependencies, it is a good idea to make sure that the resolutions defined still apply and are correct. | ||
|
|
||
| ### Logging | ||
|
|
||
| When logging, we try to adher to the following guideliness: | ||
|
|
||
| Usage of `console.log` and `console.error` directly is discouraged (except for quick debugging locally). Instead, use one of the logger libraries (to output json logs which are easier to index). | ||
| When logging, use one of the **log level** described below: | ||
|
|
||
| | Level | Description | Examples | | ||
| | ------- | ----------- | -- | | ||
| | `silly` | For very detailed logs (rarely used). | - | | ||
| | `debug` | Logging of info that could be useful for developers when debugging certain issues in production. | `"payload: {>JSON<} "`<br></br>`"Reloading data X from DB"` | | ||
| | `verbose` | Logging of common events. | `"File X updated"` | | ||
| | `info` | Logging of significant / uncommon events.<br></br>_Note: If an event happens often or many times, use `verbose` instead._ | `"Initializing TSR..."`<br></br>`"Starting nightly cronjob..."`<br></br>`"Snapshot X restored"`<br></br>`"Not allowing removal of current playing segment 'xyz', making segment unsynced instead"`<br></br>`"PeripheralDevice X connected"` | | ||
| | `warn` | Used when something unexpected happened, but not necessarily due to an application bug.<br></br>These logs don't have to be acted upon directly, but could be useful to provide context to a dev/sysadmin while troubleshooting an issue. | `"PeripheralDevice X disconnected"`<br></br>`"User Error: Cannot activate Rundown (Rundown not found)" `<br></br>`"mosRoItemDelete NOT SUPPORTED"` | | ||
| | `error` | Used when something went _wrong_, preventing something from functioning.<br></br>A logged `error` should always result in a sysadmin / developer looking into the issue.<br></br>_Note: Don't use `error` for things that are out of the app's control, such as user error._ | `"Cannot read property 'length' of undefined"`<br></br>`"Failed to save Part 'X' to DB"`| | ||
| | `crit` | Fatal errors (rarely used) | - | | ||
|
|
Oops, something went wrong.