This repository is a foundational guide for contributing to and consuming from the technical content that has been provided by the IBM Garage for Technical Solution Acceleration. We will maintain a list of best practices and desired content for each repository across the organization to implement for each of their delivered assets. This will provide a positive user experience for content contributors and consumers alike!
Repository names should be explicit enough to identify the asset as standalone content, but also follow any naming patterns and conventions that similar or contextual projects have already begun using.
It is desired to avoid the use of internal acronyms and project codenames in the names of repositories that are created under the IBM Garage for Technical Solution Acceleration organization. If these issues become pervasive, you may be asked to change the name of your repository or it may be changed automatically by organization owners.
If you have questions about the name of your repository, either before or after it has been created, feel free to contact anyone mentioned in Authors and acknowledgment below for assistance.
Within reason, your asset repository should have as much information as possible in the description field so that consumers of your excellent work will know exactly what they are getting into! A few short sentences should be more than enough to steer consumers in the right direction.
Additionally, once your repository is created, adding a few relevant Topics is a great way for consumers to find your content organically and through other relevantly-tagged repositories.
Per GitHub's renaming repository,
On October 1, 2020, any new repositories you create will use main as the default branch, instead of master. This change does not impact any of your existing repositories: existing repositories will continue to have the same default branch they have now.
As this will be a long-term change with the majority of content in this repository being created after the October 1st, 2020 transition point - any content that is migrated over from existing organizations or repositories should align with the main branch naming strategy for consumer consistency.
Similar to Tom Preston-Werner's notion of README-Driven Development, we want to make sure that consumers of content from the IBM Garage for Technical Solution Acceleration organization have as much context and information as they need to from their initial point of entry.
When creating new repositories inside the organization, please focus on making the repository's main README file as robust as possible, including as much relevant information as necessary for consumers to be productive within minutes!
As a reference, please use https://www.makeareadme.com/ for guidance, pointers, and inspiration for complete and robust README content.
Apache License 2.0 is the default license for all open-sourced IBM Garage for Technical Solution Acceleration-based assets.
Unless otherwise specifically required, all asset repositories created under https://github.com/ibm-garage-tsa should contain the Apache License 2.0 upon creation.
Contribution to any project found in the IBM Garage for Technical Solution Acceleration organization is actively encouraged. If you are new to open source software and projects, but would still like to learn more on how to contribute, please visit the How to Contribute to Open Source Software guide found in the Open Source Guides site, published by GitHub. There is great information in how to submit a contribution and links to some external sites that allow you to practice.
As a project or repository owner, it is requested that your project repository contain a CONTRIBUTING.md file to direct users on how they can interact and contribute to your repository. You can use this repository's template CONTRIBUTING.md as a starter and adapt as needed to your specific project and team's needs.
- Rick Osowski (@osowski)
This repository is licensed under the Apache 2.0.