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/Outline

• 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 (Python & JavaScript)

This training covers best practices for managing, testing, and documenting software projects built with Python and JavaScript.

Code Management, Versioning, and Licensing

• Use Git for source control
• Branching strategy:
  • main – stable production code
  • feature branches – new development
• Use Semantic Versioning (MAJOR.MINOR.PATCH)
• Add a LICENSE file (MIT or Apache 2.0 commonly used)
• Protect main branches with:
  • Pull / Merge Request reviews
  • Mandatory CI checks

Automation and Code Quality (Python & JS)

Python

• Linters: flake8, pylint
• Formatter: black
• Import sorting: isort
• Type checking: mypy

JavaScript

• Linter: ESLint
• Formatter: Prettier
• Type checking: TypeScript (recommended)

Best practices:

• Run linters and formatters automatically
• Keep functions small and readable
• Follow PEP 8 (Python) and standard JS style guides

Continuous Integration (CI)

CI pipelines automatically validate code on each push or pull request.

Example: GitHub Actions

name: CI

on:
  pull_request:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Python dependencies
        run: |
          pip install -r requirements.txt

      - name: Lint Python
        run: |
          flake8 .
          black --check .

      - name: Run Python tests
        run: pytest

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install JS dependencies
        run: npm ci

      - name: Lint JS
        run: npm run lint

      - name: Run JS tests
        run: npm test

Example: GitLab CI

stages:
  - lint
  - test

python_lint:
  stage: lint
  image: python:3.11
  script:
    - pip install flake8 black
    - flake8 .
    - black --check .

python_test:
  stage: test
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - pytest

js_lint:
  stage: lint
  image: node:20
  script:
    - npm ci
    - npm run lint

js_test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test

Benefits:

• Early detection of issues
• Enforced quality standards
• Reliable and repeatable builds

Automated Testing

Python

• Frameworks: pytest, unittest
• Tools:
  • pytest-cov (coverage)
  • requests-mock / responses (API mocking)

JavaScript

• Unit & integration: Jest, Vitest
• End-to-end (E2E): Cypress, Playwright

Best practices:

• Run tests automatically in CI
• Test behavior, not implementation details
• Keep test execution fast

Changelog and Commit Standards

• Maintain CHANGELOG.md
• Follow Keep a Changelog structure:
  • Added
  • Changed
  • Fixed
  • Deprecated

Conventional Commits

• feat: new feature
• fix: bug fix
• docs: documentation
• test: tests
• chore: maintenance

Issue Management and Roadmap

• Use issues to track bugs, features, and technical debt
• Organize work using milestones and boards
• Reference issues in commits and merge requests

Best Practices in Issue Creation

• Use issue templates (bug / feature)
• Apply labels:
  • python
  • javascript
  • bug
  • enhancement
  • documentation
• Always include clear reproduction steps for bugs

Documentation

Effective README

A strong README.md includes:

• Project overview
• Python / Node.js requirements
• Installation steps
• Usage examples
• Testing instructions
• License

Contributing Guide (CONTRIBUTING.md)

Should define:

• Environment setup
• Coding standards
• Commit conventions
• Pull Request workflow

API Documentation

Python

• Sphinx – documentation from docstrings
• FastAPI – automatic OpenAPI / Swagger
• MkDocs – lightweight docs

JavaScript

• Swagger / OpenAPI – REST APIs
• JSDoc – inline documentation
• Docusaurus – documentation portals

Recommended Project Structure

Example structure for a combined Python + JavaScript repository:

project-root/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── api/
│   │   └── services/
│   ├── tests/
│   ├── requirements.txt
│   └── pyproject.toml
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   └── services/
│   ├── tests/
│   ├── package.json
│   └── package-lock.json
│
├── docs/
│   ├── api/
│   └── guides/
│
├── .github/ or .gitlab/
│   └── ci/
│
├── CHANGELOG.md
├── CONTRIBUTING.md
├── README.md
└── LICENSE

Key Takeaways

• CI enforces quality for Python and JavaScript
• Automated testing reduces regressions
• Clear structure improves maintainability
• Documentation is part of the codebase