Software Architecture - Essay 3

Software Architecture - Essay 3 === OBS Studio was started in 2013 by Hugh "Jim" Bailey and quickly grew with the help of many online collaborators working to improve the software. In the present day, the software is community-driven with over 400 contributors. Because there is no real company, the autonomy must be very solid for the software development to run well This essay is divided into 7 sections, the structure of the essay is: - [Software quality process](#p1) - [Continuous integration](#p2) - [Testing](#p3) - [Hotspot components](#p4) - [Code quality](#p5) - [The quality culture](#p6) - [Technical debt](#p7) ## Software quality process A method to ensure the development of OBS Studio is the use of software quality processes and how they are applied. This section will cover this concept. ### Forking In order for developers to contribute to the software, they need to fork the Github repository. Forking is creating a copy of a repository where you can freely experiment with changes without actually affecting the original project [^githubfork]. To add to the original project, the developer then has to create a branch from their fork and submit a pull request from that branch into the master branch of the original Github project. Such a pull request needs to be reviewed by other developers that in turn decide whether they accept, reject, or request changes for the pull request. ### Pull request In OBS Studio's case, you also need to provide detailed information about the pull request together with a checklist that is checked off. The detailed information entails a description of the pull request, motivation, and context as to why the changes were made, the way the changes have been tested, and the types of changes that are made (e.g. Bug fix, documentation, etc.). The checklist consists of the following tasks: - My code has been run through the clang-format - I have read the contributing document - My code is not in the master branch - The code has been tested - All commit messages are properly formatted and commits squashed where appropriate. - I have included updates to all appropriate documentation. The clang-format is about the continuous integration that is applied, which will be addressed in the next section. The contributing document shows a list of coding conventions OBS Studio developers must abide by. #### Coding For coding these consist of using the kernel normal form which is a specific coding style, avoiding trailing spaces, tabs needing to be used for indentation, and a line of code not being longer than 80 columns. #### Committing For committing these changes are as follows; make use of the 50/72 standard for commits, which means 50 maximum of 50 characters for a commit message, and a full description afterward, wrapped to 72 columns. Titles should be in the present tense, prefix each commits title with the module name it addresses followed by a colon and a space [^guideline]. ## Continuous integration Together with the aforementioned conditions that need to hold to contribute, there is also the continuous integration that is applied when making an addition. This section will cover the key elements of OBS Studio's continuous integration processes. The development team has decided that for each pull request that is made, there are 12 checks divided over 4 tools that are used for the CI. These parts are `Flatpak`, `CI Multiplatform Build`, `Azure pipeline`, and `Clang-format`. ### Flatpak Flatpak is a utility for software deployment and package management for Linux. It is advertised as offering a sandbox environment in which users can run application software in isolation from the rest of the system. This way OBS Studio can do some quick end-to-end testing when deploying their software on Linux[^flatpak]. ### CI Multiplatform Build They build the latest version on the possible platform OBS Studio is capable of running on. That is, they build the latest version on macOS 64-bit, Linux/Ubuntu 64-bit, Windows 32-bit, and Windows 64-bit. They do this by installing all parts needed to run the software on the specific platform which is specified in `main.yml`[^multiplatform]. ### Azure pipeline Azure Pipelines automatically builds and tests code projects to make them available to others. Azure Pipelines combines continuous integration (CI) and continuous delivery (CD) to constantly and consistently test and build the code[^azure]. ### Clang-format Clang is a compiler front end for C, C++, and several other programming languages. It is mainly used to compile the code and run `formatcode.sh` using `clang-format.yml` which is a script that checks the code quality. That is, it looks at whether the code is in line with the coding conventions[^github]. Next to the checks there also other actions performed in the workflow. These are `CI AppImage Build` and `Generate Documentation` . ### CI AppImage Build AppImage allows users to download an application and run it on a Linux desktop system just like in Windows or Mac applications. So it is a check to see whether providing the packages for OBS Studio for Linux desktop systems will result in any errors. They do so by running `build-appimage.yml`[^appimage]. ### Generate Documentation As the name suggests, it generates documentation for the specified places in the project. This is done running `docs.yml`[^generatedoc]. ## Testing Unfortunately, in the development of OBS Studio, automated testing is not one of the priorities. The compiling and building of the software product is the main way of testing. There is also a test folder with several general tests. But these are not nearly enough to test the whole system. When submitting a pull request all changes are mainly manually tested by the contributor and the reviewer(s)[^github]. ## Hotspot components This section will discuss the components that involved in many code changes from the past and the potential future hotspot components. We visualize the quality of OBS by the tool of CodeScene[^codescene]. From the past code changes, the top three hotspot components are: `plugins`, `UI`, and `libobs`. `plugins` is the one contains all the official plugins of OBS studio, thus it's reasonable that `plugins` is one of the hotspot. The interface of OBS is supported by Qt, hence, the commits of `UI` contains the cleanups for new versions of Qt framework. The components of `libobs` is the library of OBS, thus the commits contains a large amount of code cleanups and minor fixes. ![](https://i.imgur.com/Dw7UE84.png) Figure 1: Hotspot component of OBS studio Among all the files of OBS, the most frequently changes one is the `window-basic-main.cpp` from `UI` component, with a change frequency of 106 commits. Further analysis of the code quality will be discussed in [next section](#p5). As for hotspot in the future, there're no new big features planned for next version, the future work will mainly be improving the system, thus hotspots will focus on the `plugins` components to add more features and fixing issues of other components. ## Code quality This section focus on the code quality of hotspot components discussed on [previous section](#p4). Among all the hotspot components, the `window-basic-main.cpp` file of `UI` component is the one with most defect commits, which has 47 commits of defect and takes 44% of the total commits in this file. ![](https://i.imgur.com/HtCO9Oc.png) Figure 2: Hotspots in UI component According to the analysis of CodeScene[^codescene], the least healthy codes of all the files are all in `UI` component, with the problems of bumpy road and deeply nested complexity, which means this code has multiple nested conditional logic inside the same function. However, in `UI` component, it's essential to check the conditions of every settings and transmit these to back end functions, hence, some of the functions in `UI` needs to check these conditions by if-statement in sequence. Therefore, the poor score of `UI` component does not represent serious problems of source code. ## The quality culture The quality culture of OBS Studio is maintained by the entire community. Some useful guide documents[^guideline] are provided on github for contributors to follow. In these documents, they describe some principles of coding and commit format. In the issues and pull requests of OBS studio, there is a tag "code cleanup" which is specified for those contributions on structure refactoring and code cleaning. The fact that 160 "code cleanup" issues and pull requests accounted for a large proportion of the total reflects the community's emphasis on code maintainability and quality. And we will take one of the pull requests as examples for specific analysis. As described in this pull request[^hotkey], the hotkey interface need to be redesigned as a plugin rather than embeded in core module and RFC is used to integrate all control plugin modules. The first reason of this refactoring is that the hotkey code is mixed with others in sevearal files which is against maintainability. The other reason is that using RFC allows hotkeys to control and communicate with other input and output plugin modules[^RFC]. This code refactoring is consistent with the design concept of the entire project, that is, modular plug-inization. Through this plug-in idea, the entire project becomes very extensible and maintainable. Becides, some comments under pull requests posted by developers also reflect their awareness of quality culture. One of the examples can be: ![](https://i.imgur.com/3PnU8nV.png) Figure 3: Comment by OBS Studio developers ## An assessment of technical debt present in the system. The current system has little techincal debt, which is the consequence of a complete rework of the entire system and the emphasis on maintainability afterwards. Like we discussed earlier there is a lot of focus on the code quality as seen from all the code cleanup PRs. As well as the maintainance of it by ensuring strict rules for all changes to the system. And even though there are no current plans for major new features this should not give too much of a hassle similar to how smaller features are also implemented fairly easily. This was completly different back in 2016 when the developers wanted to add multi-platform support and realised that the system was compeltly hard coded for windows and there was no way it would work on other systems[^refractor]. Furthermore the developers also saw major techincal and coding flaws that which hindered the developers in maintaining the system and adding new features. They are all addressed in [^refractor] but we will take a look at the main ones. The main design flaws were caused by either not planning well enough or hardcoding particular features/components. This was generally because the developer didnt anticipate his project becoming so big and he just wanted to create a simple streaming software. Therefore he only added certain features later on such as the API, but these were generally hard to implement and were hacked into the project. With the rework the core developer had way more expierence with all the sub-systems and there was now also a community to help out. Thus he set out some of the main goals for the rework: * Making it multi platform since that was the feature they wanted to add before realizing how bad their system was designed. * Seperating the components more and simplifying the particular complext ones. This would make them easier to use and more maintanable. * Creating a new API and making it modular. * Improving the overall design, minimizing the design flaws and to ensure that certain features, which could not be added before, can now easily be added. Furthermore were there also some major coding flaws, which the rework intended to resolve. The main problems were inconsistent style, too many custom classes which re-invented the wheel and classes and methods that were too large and did too many things at once. That is why they introduced such strict guidelines which they still use currently and are already mentioned in this essay. So it is clear to see that there was a lot of technical debt in the system and they decided that rewriting the entire system with clear guidelines and a strict code style in mind would repay the debt and give them a clean slate. So that is indeed what they did and the guidelines were already mentioned in the section about PR quality. And this has given the current system with very little debt remaining, because you can never remove all of it for everyone at least. ## Reference [^guideline]: [OBS contributing guidelines](https://github.com/obsproject/obs-studio/blob/master/CONTRIBUTING.rst) [^hotkey]:[Hotkey pull request](https://github.com/obsproject/rfcs/pull/28) [^RFC]:[RFC](https://github.com/cpyarger/rfcs/blob/master/text/0028-reimplementation-of-hotkeys-to-controls.md) [^refractor]: [Objective of OBS refactoring](https://github.com/alesaccoia/chew-broadcaster/blob/master/README) [^githubfork]:[OBS Github forking](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) [^github]:[OBS Github](https://github.com/obsproject/obs-studio) [^azure]:[Azure pipeline](https://docs.microsoft.com/nl-nl/azure/devops/pipelines/get-started/what-is-azure-pipelines?view=azure-devops) [^multiplatform]:[CI Multiplatform Build](https://github.com/obsproject/obs-studio/actions?query=workflow%3A%22CI+Multiplatform+Build%22) [^flatpak]:[Flatpak](https://flatpak.org/) [^appimage]:[AppImage](https://appimage.org/) [^generatedoc]:[Generate documentation](https://github.com/obsproject/obs-studio/actions/workflows/docs.yml) [^codescene]:[CodeScene](https://codescene.io/)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.