Sharing the "OSS Publishing Tutorial" Created by ROUTE06, Inc.

Hey Devs!

Recently, ROUTE06, Inc. has made two products, Giselle and Liam, open-source.

• https://github.com/giselles-ai/giselle
• https://github.com/liam-hq/liam

In this article, I'll share the "OSS Publishing Tutorial" that ROUTE06, Inc.'s OSS Promotion Office created and used when making these products open-source. Some internal links and references have been omitted.

👉 ROUTE06, Inc.'s OSS Promotion Office functions as an Open Source Program Office (OSPO), responsible for promoting OSS utilization, managing risks, supporting community contributions, and advancing the open-sourcing of internal products and projects.

• OSS Publishing Tutorial
  • 1. Preparation
  • 2. Repository Setup
    • 2-1. Setup Items
      • Column: What to write in [INSERT CONTACT EMAIL]?
    • 2-2. Create a Slack channel #gh-*
  • 3. Pre-Publishing Review
    • 3-1. Conduct a Security Review
    • 3-2. Confirm Compliance
    • 3-3. Obtain Internal Approval for OSS Publishing
  • 4. Repository Publishing
    • 4-1. Publish the Repository
    • 4-2. Conduct a Post-Publishing Review by the OSS Promotion Office
• Conclusion
• Supplement: About Giselle and Liam as OSS

OSS Publishing Tutorial

This is a tutorial on how to publish an OSS repository on GitHub.

💡 The OSS Promotion Office is available to consult on topics like license selection and other aspects.

1. Preparation

1. Decide which GitHub organization will host the repository
   • Choose whether to create the repository under https://github.com/route06inc or another organization¹
2. Decide the repository name
   • Choose a name for the repository under the organization
3. Decide when to make the repository public
   • Typically, start as Private and switch to Public when preparations are complete
   • If everything is ready, create it as Public from the beginning
4. Agree to enable all repository features except for Wikis
   • Issues, Pull requests, Discussions, Projects
   • Note: To encourage external contributions, this is the default policy
5. Decide whether to use English, Japanese, or both in various parts of the repository
   • Repository description
   • Issues, Pull Requests, Discussions, Projects
     • Title, Content, Comments
   • Source code comments
   • Git commit messages
   • Documentation
     • README.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md
       • English is required, Japanese is optional. Both are allowed
     • Other text files
   • Note: Decide within the limits of what won't hinder development. Add this later to CONTRIBUTING.md
6. Decide the name of the private repository for internal communication
   • Create a private repository for purposes like the following. For example, route06/*-internal
     • Medium- to long-term planning
     • Discussions about vulnerabilities not yet ready for disclosure
     • Discussions involving confidential or collaborator-only² information
     • Others
   • Use public repositories whenever possible to ensure transparency. For example:
     • Feature proposals
     • Bug reports
     • General Q&A
     • Code reviews
     • Documentation updates
7. Decide on the repository's operation policy immediately after publishing
   • While it's unlikely there will be too many contributions right after publishing, set some guidelines. For example:
     • Keep operations light at the start
     • When an Issue, Pull Request, or Discussion from a Contributor comes in, ⚪︎⚪︎ responds to it as needed
     • Establish triage policies when contributions increase

2. Repository Setup

2-1. Setup Items

Create a repository in the organization decided in "1. Preparation" and proceed with the setup. All items are required unless otherwise discussed.

Column: What to write in [INSERT CONTACT EMAIL]?

In templates like CODE_OF_CONDUCT.md and SECURITY.md, replace [INSERT CONTACT EMAIL] as follows:

If you want to use separate email addresses for each purpose:

• conduct@example.com
  • Specify in CODE_OF_CONDUCT.md
• security@example.com
  • Specify in SECURITY.md

If you want a single email address for all community inquiries:

• Example 1: community@example.com
• Example 2: oss@example.com

2-2. Create a Slack channel #gh-*

💡 At ROUTE06, Inc., creating a #gh-* Slack channel for GitHub repository notifications is encouraged.

Once the channel is created, run the following command in it. Replace ORG/REPO as needed.

/github subscribe ORG/REPO issues, pulls, commits, releases, deployments, reviews, comments, discussions

This will enable notifications. Check the configuration with /github subscribe list features.

By default, notifications are posted in threads. Disable this by following these steps:

1. Run /github settings in the channel
2. Click Disable under "Disable threading for Pull Request and Issue notifications"

ref: https://github.com/integrations/slack/issues/1500#issuecomment-1335564029

3. Pre-Publishing Review

3-1. Conduct a Security Review

• Verify that the SECURITY.md file is added to the repository and that it clearly outlines the security policy and vulnerability reporting procedure
• Ensure that the following GHAS features are enabled
  • Code scanning (CodeQL)
    • Confirm the .github/workflows/codeql.yml commit
  • Secret scanning and Push protection
• Confirm that Dependabot Alerts is enabled
• Ensure that no internal information is hardcoded in the repository's source code
  • Example: Preventing non-company email addresses from being registered as a safeguard
• Confirm there are no internal links in the repository's source code or commit messages
  • Example: Slack URLs, internal private repository URLs, issue numbers starting with #, etc.
  • If such links exist, they do not need to be erased from history with git rebase. Just ensure they are not included going forward
• Verify that no proprietary names appear in the repository's source code or commit messages
  • Example: $ git log -p | grep -E '(◯◯|□□|△△)'
• Use full commit hashes for third-party GitHub Actions version specifications (optional)
  • Example: - uses: owner/action-name@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v1.0.0

3-2. Confirm Compliance

• Verify licensing
  • Ensure the LICENSE file is added to the repository and that the selected license applies appropriately to the source code without infringing on third-party rights
  • Confirm compatibility between the repository's license and the licenses of dependent libraries
  • Reference:
    • How We Started Continuous OSS License Monitoring with License Finder - DEV Community
• Check export regulations
  • Confirm that the project does not include technologies subject to export regulations

3-3. Obtain Internal Approval for OSS Publishing

This step requires that you first decide on a license for your project. Handle this as soon as the license is finalized.

4. Repository Publishing

4-1. Publish the Repository

Coordinate as needed with a blog post or a press release.

4-2. Conduct a Post-Publishing Review by the OSS Promotion Office

Even after publishing the repository, verify that the repository settings are configured as intended.

• Check for any omissions in "2. Repository Setup"
• Confirm that the following GHAS features are enabled: Code scanning (CodeQL), Secret scanning, Push protection
• Verify that Dependabot Alerts is enabled
• Ensure the "Report a Vulnerability" link in the repository's SECURITY.md file works for both:
  • Members of the GitHub organization
  • External users of the GitHub organization
    • If the link results in a 404 Not Found error for external users, Private vulnerability reporting might be disabled
• Confirm that Reported content in Reported content settings is set to Prior contributors and collaborators
  • 💡 This setting restricts or relaxes who can report vulnerabilities

Conclusion

In this article, I shared the "OSS Publishing Tutorial" that we created and used when making Giselle and Liam open-source.

Although I have experience with open-sourcing projects personally, I initially thought, "Isn't it just about publishing a repository?" However, in a professional setting, numerous other things to consider came to light, resulting in this detailed "OSS Publishing Tutorial." We plan to keep updating it moving forward.

I hope this serves as a useful reference.

Supplement: About Giselle and Liam as OSS

The giselles-ai/giselle repository recently published as OSS is for Giselle, a platform that enables no-code creation of agents and workflows utilizing generative AI. Detailed information can be found on the Giselle service website: https://giselles.ai/.

The liam-hq/liam repository is for Liam, a tool that effortlessly generates beautiful and easy-to-read ER diagrams. Detailed information can be found on the Liam service website: https://liambx.com/.

1. Example: https://github.com/giselles-ai, https://github.com/liam-hq ↄ1�7/a>

2. ROUTE06, Inc. employees or partners with Admin/Write permissions for the repository ↄ1�7/a>

3. Requires using the default CodeQL configuration to set it as a required status before PR merges ↄ1�7/a>