Open-source software release protocol

[amaurigmartins]

Repository name

JustTesting.jl

Version tag

v0.0.1

IP and Legal Requirements

• Written consent secured from faculty advisor or PI
• Software disclosure submitted to tech transfer/IP office
• Funding/sponsorship contracts reviewed for restrictions or obligations
• Written consent secured from all co-developers and collaborators
• Verified no active or pending patents are compromised by open release
• Verified absence of sensitive data (personal, confidential, regulated tech)
• Third-party licenses audited and documented to confirm compatibility with the repository
• All findings and products of the codebase being open-sourced have been published/accepted for publication with scientific journals

Code Quality Requirements

• Codebase cleaned: no credentials, passwords, API keys, sensitive URLs, or debug code
• Out-of-the-box functionality confirmed in a clean environment
• Reproducibility ensured: scripts or datasets included to reproduce main results
• Dependencies clearly documented (requirements.txt, compiler info, etc.)
• Basic tests or validation scripts included demonstrating key functionality
• Peer or self-review performed for code readability and usability

Documentation Requirements

• Comprehensive README.md created with clear purpose, installation and usage instructions
• CHANGELOG.md created following proper standards (Keep a Changelog)
• Citation instructions provided (CITATION.cff, DOI links, publication references)
• Appropriate LICENSE.md file attached at repository root
• Funding agencies, institutional support, and contributors properly acknowledged
• Contributing guidelines included for external collaborators (if applicable)

Repository Finalization Requirements

• Repository structure clearly organized (src/, examples/, docs/, etc.)
• Final pre-release sanity check performed (installation from scratch, test examples)
• Release clearly tagged and versioned (e.g., v1.0.0) with release notes
• Repository ready to be set to public visibility
• Release announcement prepared for internal and external channels
• Repository archived with DOI (optional, via Zenodo)

Additional Notes

Open-source software release protocol

Executive summary

This document outlines a standardized GitHub-based workflow for ensuring all software repositories meet institutional compliance requirements before public release. The protocol implements a structured, documented approval process integrated directly into the existing GitHub infrastructure.

The proposed strategy is also compatible with the self-hosted KU Leuven GitLab service.

Objectives

1. Ensure all publicly released software complies with institutional requirements
2. Create a standardized, trackable process for pre-release validation
3. Establish clear accountability for both repository owners and approvers
4. Prevent inadvertent release of sensitive information or intellectual property
5. Document compliance for auditing purposes

Implementation overview

The workflow utilizes native issue templates and branch protection rules native to GitHub to create a pre-release approval protocol. Repository owners must complete a comprehensive checklist covering IP clearance, code quality, documentation standards, and finalization steps before release approval.

Process flow

1. Repository owner initiates release by creating an approval request issue
2. Owner completes comprehensive compliance checklist
3. Designated organization approver reviews submission
4. Upon approval, repository is cleared for public release
5. Complete audit trail maintained within GitHub

Technical implementation

The solution is implemented through:

1. Standardized issue template (.github/ISSUE_TEMPLATE/release_approval.yml)

   • Structured form with mandatory fields
   • Comprehensive compliance checklists
   • Institutional requirements formalized in code

2. Branch protection rules

   • Prevents repository visibility changes without approved issues
   • Blocks release tag creation until compliance is verified

3. Automated validation

   • GitHub Actions verify compliance documentation
   • Ensures all checks are completed before approval

Roles and responsibilities

Repository owner

• Completes comprehensive pre-release checklist
• Provides documentation of compliance with all requirements
• Implements any required changes identified during review

Organization approver

• Who? Electa-Git group member with Ownership role or KUL GitLab admin
• Reviews submission for completeness and accuracy
• Verifies critical compliance elements (IP clearance, sensitive data removal)
• Approves or rejects release requests with appropriate feedback
• Maintains institutional standards across all repositories
• Applies the tag 'release-approved' when done

Institutional email

amauri.martinsbritto@kuleuven.be

[amaurigmartins]

Moved template to: https://github.com/Electa-Git/etch-oss-template/blob/main/CHECKLIST.md