OSS

THIS IS A DRAFT

This text may not be complete.

title

OSS Training Course

author

Lukasz Sokolowski

OSS

OSS Training Materials

Copyright Notice

Copyright © 2004-2026 by NobleProg Limited All rights reserved.

This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise.

Introduction

• Code management, versioning, and licensing
• Automation and code quality (best practices)
• Continuous Integration (CI) on GitHub/GitLab
• Automated testing (unit, integration, end-to-end)
• Changelog (Keep a Changelog, Conventional Commits)
• Issue management and roadmap
• Best practices in issue creation (templates, labels, milestones)
• Documentation
  • Effective README: objectives, installation, usage, contributions
  • Contributing Guide (CONTRIBUTING.md)
  • API documentation (Swagger, Sphinx, Docusaurus, etc.)

Modern Software Development Practices

This training provides an overview of best practices for code management, automation, CI, testing, issue tracking, and documentation.

Code Management, Versioning, and Licensing

• Use Git for source code management
• Adopt a clear branching strategy:
  • main / master for stable releases
  • feature branches for development
• Follow Semantic Versioning (SemVer) (MAJOR.MINOR.PATCH)
• Always include a LICENSE file
• Common licenses: MIT, Apache 2.0, GPL
• Protect main branches with code reviews and CI checks

Automation and Code Quality (Best Practices)

• Automate repetitive tasks:
  • Linting
  • Formatting
  • Builds
  • Tests
• Enforce code quality using:
  • Linters (ESLint, Flake8, Pylint)
  • Formatters (Prettier, Black)
• Follow consistent coding standards
• Keep code readable, modular, and well-commented

Continuous Integration (CI)

GitHub Actions and GitLab CI enable automated workflows.

Typical CI pipeline:

1. Install dependencies
2. Run linting and formatting checks
3. Execute automated tests
4. Build artifacts

Benefits:

• Early detection of issues
• Consistent quality checks
• Faster feedback for developers

Automated Testing

Testing types:

• Unit Tests
  • Test individual functions or components
• Integration Tests
  • Test interactions between components
• End-to-End (E2E) Tests
  • Test complete user workflows

Best practices:

• Run tests automatically in CI
• Keep tests fast and reliable
• Track coverage, but prioritize meaningful tests

Changelog and Commit Standards

• Maintain a CHANGELOG.md
• Follow Keep a Changelog format:
  • Added
  • Changed
  • Fixed
  • Deprecated
• Use Conventional Commits format:
  • feat:
  • fix:
  • docs:
  • chore:

Benefits:

• Clear project history
• Easier releases
• Improved automation

Issue Management and Roadmap

• Use issues to track:
  • Bugs
  • Features
  • Tasks
  • Technical debt
• Maintain a project roadmap
• Use milestones or project boards
• Reference issues in commits and pull requests

Best Practices in Issue Creation

• Use issue templates (bug reports, feature requests)
• Apply labels (bug, enhancement, documentation, priority)
• Group issues with milestones
• Write clear titles and descriptions
• Include steps to reproduce for bugs

Documentation

Documentation is a core part of the project:

• Improves onboarding
• Reduces support overhead
• Increases adoption and maintainability

Effective README

A good README.md should include:

• Project objectives and overview
• Installation instructions
• Usage examples
• Configuration details
• Contribution overview
• License information

Contributing Guide (CONTRIBUTING.md)

The contributing guide should describe:

• How to fork and clone the repository
• Branching strategy
• Commit and testing requirements
• Pull request workflow
• Code review process
• Code of conduct (optional)

API Documentation

API documentation should be clear and up to date.

Common tools:

• Swagger / OpenAPI – REST APIs
• Sphinx – Python projects
• Docusaurus – Developer portals

Best practices:

• Auto-generate documentation from source code
• Provide examples and error responses
• Version API documentation

Key Takeaways

• Automate wherever possible
• Enforce quality with CI and testing
• Standardize commits, changelogs, and issues
• Treat documentation as a first-class citizen