Using software based on open source code - Tools and methods

One of the most crucial tools for managing source code in OSS projects, whether they are self-developed or not, is version control systems. The most popular ones are based on Git, but there are others as well. If you follow the Git track, you basically have a choice among the three major ones: GitHub, GitLab, and Bitbucket. Be aware that only GitLab is open source, while the other two are proprietary. With a good system, you can easily keep a list of all changes made, see who has developed and committed the changes. When something goes wrong, and the application suddenly doesn't work as it should, it's also straightforward to roll back to the last functioning version.

In addition to traceability, it also opens up the possibility of collaborating more easily in various development projects. It becomes quite easy to follow everyone's proposed changes (Pull Requests) and jointly determine what is most prioritized to implement. At the same time, you minimize the risk of overwriting each other's changes in the project. Of course, conflicts can still arise, but these are usually presented in an educational and easily understandable way, making it easy to resolve.

There are plenty of tools for analyzing static source code, and one of the most popular is SonarQube, where you can easily create reports and establish so-called 'toll gates' where you can specify different quality levels and automate quality control, such as specifying a threshold for how much of your source code must be covered by unit tests.

In addition to testing static source code, you should also test the pre-built applications (images). These contain much more than just your source code since they also include all dependencies on other libraries along with your custom-developed software. Here you can get lots of tips on various vulnerabilities and how to improve your application. Jfrog Xray is a product many use for this purpose.

Testing is actually a chapter in itself and includes much more than the things we have already mentioned. Tests such as SAST/DAST, application security tests, penetration tests, functional tests, exploratory tests, performance tests, security tests, end-to-end tests, etc., should be included in all quality assurance projects, and most can be automated to some extent and activated in a pipeline

To facilitate the management of dependencies, libraries, and packages in development projects, it is appropriate to use a so-called package manager. There are many popular options, but some of the most used are npm for JavaScript, pip for Python, and Maven for Java-based applications.

The npm package manager is used with Node.js and has a configuration file called package.json where all packages and their associated versions are specified. In npm, there are also built-in tools to automatically check dependencies and get an overview of the security status of the various components, along with recommendations on how to address any security issues.

In pip, a file called requirements.txt is used, where everything is specified. The logic is very similar to how it is handled in npm for JavaScript, but there are some differences when working with Python.

With Maven, you have a file called pom.xml where you can list all dependencies and plugins your project uses. You can also use it to point out different repositories you use, both internal and external.

Don't forget to read up on the various license models and which ones apply to which products/plugins/modules/libraries. This can be a real jungle, so make sure to have this under control so that you don't suddenly find yourself in a situation where your software violates the license rules. In some license models, for example, you are expected to make your own source code available when using the OSS project, and that may not always be what you want. An important thing is to 'whitelist' all license models that your organization can use without reservations. Also, create a 'blacklist' where you put all license models that should never be used. For all models not included in these lists, you should ideally create an approval process that must be gone through on a case-by-case basis. There are hundreds of different license models, but not quite as many approved by the Open Source Initiative (OSI), so start with those that are approved.

Fortunately, there are also plenty of tools here that can help you scan license models and automatically provide recommendations, so search the market and experiment to find the tool that suits you best.

The key to successful OSS projects is comprehensive/easy-to-understand documentation that is transparent, clear, and easily accessible. Documentation can mean many different things and target several different audiences. As an absolute minimum, you should always ensure that there is a clear README in the source code project in your repository. But in addition to that, you also need proper user documentation where you gather various guides, routine descriptions, manuals, etc., aimed at end-users. Here, it's important not to get too caught up in technical details but to focus on the actual use of the product. For administrators or superusers, it's also important to have updated documentation showing how to maintain and update the software, so-called lifecycle management, but also more concrete tasks such as user management, installation, configuration, monitoring, and troubleshooting.

Another type of documentation is aimed at developers and is a much more technical description of your project. Here, you can describe APIs, provide code examples, and go into a bit more technical details regarding the system's architecture.

Also, remember to document your source code files extensively. The more information there is in the source code files about thoughts and ideas regarding various things, the easier it is for new developers to join the team and start contributing.

As we described in our blog series about putting together the optimal development team, there are quite a few concrete things you can do with simple means to create an atmosphere where you facilitate collaboration and where there is a high ceiling and it's allowed to fail. Especially, look at article number four in the series, which is about just that. Also, use simple tools to communicate with each other. For faster, short matters, you can use software like Mattermost, Slack, Discord, etc., while for matters that may not be as urgent, you can get by with regular email. And for more static communication, discussion forums, mailing lists, or a wiki can work wonders.

When developers contribute to the project, it's also important that you have standardized the work on how this should be done. The most common way is for the developer to create a Pull Request (PR) that someone else must approve. For larger changes, you can work with Code Reviews where developers can collectively discuss solutions.

Tools and methods may vary depending on the development language and platform you use in your project, but on a more general level, they are useful to facilitate work with OSS projects. It's also important to be flexible and adapt your work methodology to the project's specific needs and development scale. In the next article, we plan to take a closer look at how you can assess the activity level in different projects and how you can compare them with each other.