OSS

From Training Material
Revision as of 22:10, 12 February 2026 by Lsokolowski1 (talk | contribs)
Jump to navigation Jump to search

THIS IS A DRAFT

This text may not be complete.

title
OSS Training Course
author
Lukasz Sokolowski


OSS

OSS Training Materials

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

Open Source Best Practices (Python & JavaScript)

This section extends the project guidelines with patterns commonly used in successful open source projects.

Separate CI Pipelines per Service

In multi-service or monorepo projects, each service should have an independent CI pipeline.

Benefits:

  • Faster CI execution
  • Clear ownership per service
  • Reduced coupling between frontend and backend

GitHub Actions (Per Service)

Each service has its own workflow file. 

.github/workflows/
├── backend-ci.yml
└── frontend-ci.yml

Example: Backend CI

name: Backend CI

on:
  push:
    paths:
      - "backend/**"
  pull_request:
    paths:
      - "backend/**"

jobs:
  backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install -r backend/requirements.txt
      - run: flake8 backend
      - run: pytest backend/tests

Example: Frontend CI

name: Frontend CI

on:
  push:
    paths:
      - "frontend/**"
  pull_request:
    paths:
      - "frontend/**"

jobs:
  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: cd frontend && npm ci
      - run: cd frontend && npm run lint
      - run: cd frontend && npm test

GitLab CI (Per Service)

backend:
  stage: test
  rules:
    - changes:
        - backend/**/*
  image: python:3.11
  script:
    - pip install -r backend/requirements.txt
    - pytest backend/tests

Monorepo vs Multirepo

Choosing the right repository strategy is critical for scalability.

Aspect Monorepo Multirepo
Code location Single repository One repository per service
CI complexity Higher Lower
Dependency sharing Easy Requires versioning
Access control Unified Granular
Tooling Requires advanced CI Simpler
Open source friendliness Good for small teams Best for large ecosystems

Recommendations:

  • Monorepo – small teams, tight coupling, shared releases
  • Multirepo – independent services, different release cycles, large communities

Issue Templates (Wiki Format)

Clear issue templates improve collaboration and contributor experience.

Bug Report

== Description ==
A clear and concise description of the bug.

== Steps to Reproduce ==
# Step 1
# Step 2
# Step 3

== Expected Behavior ==
What you expected to happen.

== Actual Behavior ==
What actually happened.

== Environment ==
* OS:
* Python / Node.js version:
* Browser (if applicable):

== Additional Context ==
Logs, screenshots, or links.

Feature Request

== Summary ==
Short description of the requested feature.

== Motivation ==
Why is this feature needed?

== Proposed Solution ==
Describe the preferred solution.

== Alternatives ==
Other approaches considered.

== Additional Context ==
Links, mockups, or references.

Documentation Issue

== Documentation Section ==
Which page or file needs improvement?

== Problem ==
What is unclear, missing, or incorrect?

== Suggested Improvement ==
Proposed text or structure.

Open Source Project Best Practices

These practices help attract and retain contributors.

Governance and Transparency

  • Define maintainers and roles
  • Use public roadmaps
  • Make decisions in issues and PRs

Contribution Experience

  • Clear README and CONTRIBUTING.md
  • Friendly issue templates
  • Label beginner issues (e.g. good first issue)

Licensing and Legal

  • Always include a LICENSE file
  • Ensure dependencies are license-compatible
  • Avoid committing secrets or credentials

Community Standards

  • Add a Code of Conduct (e.g. Contributor Covenant)
  • Enforce respectful communication
  • Moderate discussions consistently

Release Management

  • Use semantic versioning
  • Maintain a changelog
  • Tag releases
  • Automate releases where possible

Security

  • Provide a SECURITY.md
  • Define responsible disclosure process
  • Keep dependencies up to date

Open Source Checklist

  • README.md
  • CONTRIBUTING.md
  • CHANGELOG.md
  • LICENSE
  • CODE_OF_CONDUCT.md
  • SECURITY.md
  • CI pipelines enabled
  • Issue and PR templates
Retrieved from "https://training-course-material.com/index.php?title=OSS&oldid=89191"