OSS: Difference between revisions
Jump to navigation
Jump to search
Lsokolowski1 (talk | contribs) |
Lsokolowski1 (talk | contribs) mNo edit summary |
||
| Line 49: | Line 49: | ||
Key tools like GitHub, GitLab, and Bitbucket support both centralized (CVCS) and distributed (DVCS) version control, with Git being the most widely adopted DVCS. These platforms enable modern workflows such as GitOps, CI/CD pipelines, and pull request-based code reviews, enhancing development speed and system reliability. | Key tools like GitHub, GitLab, and Bitbucket support both centralized (CVCS) and distributed (DVCS) version control, with Git being the most widely adopted DVCS. These platforms enable modern workflows such as GitOps, CI/CD pipelines, and pull request-based code reviews, enhancing development speed and system reliability. | ||
<!-- VER1 | |||
--- | |||
## Slide 1 — Title | |||
**Modern Software Development Practices** | |||
Code, Quality, CI, Testing, and Documentation | |||
--- | |||
## Slide 2 — Code Management, Versioning & Licensing | |||
* Use **Git** for source control | |||
* Adopt a clear branching strategy: | |||
* `main` / `master`, `develop`, feature branches | |||
* Versioning: | |||
* **Semantic Versioning (SemVer)**: `MAJOR.MINOR.PATCH` | |||
* Licensing: | |||
* Always include a `LICENSE` file | |||
* Common licenses: MIT, Apache 2.0, GPL | |||
* Protect main branches with reviews & CI checks | |||
--- | |||
## Slide 3 — Automation & Code Quality (Best Practices) | |||
* Automate repetitive tasks: | |||
* Linting, formatting, builds, tests | |||
* Enforce code quality with: | |||
* Linters (ESLint, Flake8, Pylint) | |||
* Formatters (Prettier, Black) | |||
* Follow coding standards & style guides | |||
* Keep code small, readable, and well-commented | |||
--- | |||
## Slide 4 — Continuous Integration (CI) | |||
**GitHub Actions / GitLab CI** | |||
* Automatically run on: | |||
* Pull Requests / Merge Requests | |||
* Push to main branches | |||
* Typical CI pipeline: | |||
1. Install dependencies | |||
2. Lint & format check | |||
3. Run tests | |||
4. Build artifacts | |||
* Fail fast → catch issues early | |||
--- | |||
## Slide 5 — Automated Testing | |||
* **Unit Tests** | |||
* Test small, isolated functions | |||
* **Integration Tests** | |||
* Test interactions between components | |||
* **End-to-End (E2E) Tests** | |||
* Test full user workflows | |||
* Best practices: | |||
* Tests run automatically in CI | |||
* Keep tests fast & deterministic | |||
* Measure coverage (but don’t chase 100%) | |||
--- | |||
## Slide 6 — Changelog & Commit Standards | |||
* Maintain a `CHANGELOG.md` | |||
* Follow **Keep a Changelog** | |||
* Sections: Added, Changed, Fixed, Deprecated | |||
* Use **Conventional Commits** | |||
* `feat:`, `fix:`, `docs:`, `chore:` | |||
* Benefits: | |||
* Clear project history | |||
* Easier releases & automation | |||
--- | |||
## Slide 7 — Issue Management & Roadmap | |||
* Use issues to track: | |||
* Bugs, features, tasks, ideas | |||
* Maintain a roadmap: | |||
* Short-term vs long-term goals | |||
* Use milestones or project boards | |||
* Keep issues updated and prioritized | |||
* Close issues with references to commits/PRs | |||
--- | |||
## Slide 8 — Best Practices for Issue Creation | |||
* Use **issue templates**: | |||
* Bug report | |||
* Feature request | |||
* Apply **labels**: | |||
* `bug`, `enhancement`, `documentation`, `priority` | |||
* Use **milestones**: | |||
* Group issues by release/version | |||
* Write clear titles & descriptions | |||
* Include steps to reproduce (for bugs) | |||
--- | |||
## Slide 9 — Documentation (Why It Matters) | |||
* Documentation is part of the product | |||
* Helps: | |||
* New contributors onboard faster | |||
* Users adopt your software | |||
* Reduce support questions | |||
* Keep docs: | |||
* Clear, concise, and up-to-date | |||
--- | |||
## Slide 10 — Effective README.md | |||
A good README should include: | |||
* **Project objectives & overview** | |||
* **Installation instructions** | |||
* **Usage examples** | |||
* **Configuration (if applicable)** | |||
* **Contribution guidelines (brief)** | |||
* **License information** | |||
--- | |||
## Slide 11 — Contributing Guide (CONTRIBUTING.md) | |||
* How to: | |||
* Fork & clone the repo | |||
* Create branches | |||
* Write commits & tests | |||
* Code style & standards | |||
* Pull Request process | |||
* Expected review workflow | |||
* Code of Conduct (optional but recommended) | |||
--- | |||
## Slide 12 — API Documentation | |||
* Keep APIs well documented and discoverable | |||
* Common tools: | |||
* **Swagger / OpenAPI** (REST APIs) | |||
* **Sphinx** (Python) | |||
* **Docusaurus** (developer portals) | |||
* Best practices: | |||
* Auto-generate docs from code | |||
* Include examples & error responses | |||
* Version your API docs | |||
--- | |||
## Slide 13 — Key Takeaways | |||
* Automate everything you can | |||
* Enforce quality with CI & testing | |||
* Keep issues, commits, and changelogs consistent | |||
* Treat documentation as a first-class citizen | |||
* Small discipline upfront → big savings later 🚀 | |||
--- | |||
--> | |||
Revision as of 21:43, 12 February 2026
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.)
Intro Con't
- TODO
Code management, versioning, and licensing
Code management
- systematic handling of source code throughout its lifecycle
- including: tracking changes, organizing files, and enabling collaboration
- ensures code is reliable, traceable, and maintainable across teams and over time
Versioning
- assigning unique identifiers to different states of a codebase
- developers can track modifications, revert to previous versions, and understand who made changes and why
- this is foundational for collaboration, debugging, and ensuring code quality
Licensing
- governs how software and its source code can be used, modified, and distributed
- Open-source tools like Git are released under permissive licenses
- such as the GNU General Public License (GPL) version 2.0 - it guarantees users the freedom to share and modify the software
- However, organizations must consider licensing implications
- when using version control platforms - especially with AI features
- public repositories may be used to train models
- potentially raising intellectual property concerns
Key tools like GitHub, GitLab, and Bitbucket support both centralized (CVCS) and distributed (DVCS) version control, with Git being the most widely adopted DVCS. These platforms enable modern workflows such as GitOps, CI/CD pipelines, and pull request-based code reviews, enhancing development speed and system reliability.
