365Soft Docs
Main Site

Updating Repositories

This is the recommended default workflow for public 365Soft Labs repositories. It follows standard open source practice: discuss meaningful changes early, keep pull requests small, run checks before review, and require explicit maintainer approval before merge.

Core Principles

  • Start with an issue or discussion for any non-trivial change.
  • Keep each pull request focused on one problem or one coherent improvement.
  • Update tests, docs, and examples when public behavior changes.
  • Do not merge with failing CI or unresolved review comments.
  • Prefer squash merges to keep public history readable.

When to Open an Issue First

Open an issue before coding if the change affects:

  • Public APIs, CLI commands, or user-facing behavior.
  • Security, auth, permissions, deployment, release, or billing logic.
  • Repository structure, dependencies, or architecture.
  • A bug that needs reproduction details before review can be meaningful.

Small typo fixes, broken links, and tightly scoped documentation corrections can usually go straight to a pull request.

Recommended Workflow

  1. Open or reference an issue describing the problem, scope, and expected outcome.
  2. Create a short-lived branch for one change set.
  3. Make the smallest change that fully solves the problem.
  4. Add tests, docs, examples, or screenshots when they improve review quality.
  5. Run local checks before opening the pull request.
  6. Open a pull request with a clear summary, linked issue, and validation notes.
  7. Wait for maintainer review and required approvals before merge.

Pull Request Checklist

  • What changed?
  • Why was the change needed?
  • How was it tested?
  • Does it affect public behavior, install flows, or release notes?
  • Are there security, data handling, or operational risks?

Approval Process

Change type Minimum approval Additional requirements
Docs-only fixes, copy changes, broken links 1 maintainer approval No failing checks
Routine code, test, or example changes 1 maintainer approval CI green and review comments resolved
Security, auth, deployment, release, billing, or data-handling changes 2 maintainer approvals No self-merge, plus risk notes and validation evidence
Large refactors or public API / CLI changes 2 maintainer approvals Linked issue or design discussion required

Maintainer Review Standard

  • Check correctness, scope discipline, and backward-compatibility impact.
  • Confirm changed behavior has adequate tests or validation evidence.
  • Check whether user-facing docs or migration notes need updates.
  • Review for secret handling, permission changes, and other security risks.

Approvals should be explicit on the pull request. If the author pushes significant follow-up commits, review should be refreshed before merge.

Merge Policy

  • Merge only when required approvals are present.
  • Merge only when required CI checks are passing.
  • Merge only when review threads are resolved.
  • Keep the branch up to date enough to avoid preventable conflicts and regressions.

Security and Sensitive Changes

  • Do not publish secrets, tokens, or internal-only identifiers in issues or pull requests.
  • Use placeholders in docs and examples.
  • Request a maintainer with security context for sensitive changes.
  • Prefer private disclosure first if the work relates to a vulnerability.

Repository Hygiene

  • Protect the default branch.
  • Require CI for merge where practical.
  • Keep issue and pull request templates current.
  • Archive or clearly label inactive repositories.
  • Document release ownership and support expectations.