A repository for files that are copied across multiple repositories.
- Rationale
- Supported Files
- Unsupported Files
- Developing
- Rebroadcast License
The Wall Brew Open Source Guidelines encourage a seamless and consistent developer experience.
While we often think about the work required to provide the tools, documentation, and automation behind that experience; we would do ourselves a disservice to ignore the cost of maintaining these files across a growing number of repositories.
To prevent individual repositories from falling out of sync, rebroadcast was established to be the primary source of truth for these files.
Since most Wall Brew repositories are written in Clojure/Clojurescript, there are several language-specific configuration files worth sharing across repositories. These configuration files work with the tools in the GitHub actions for those repositories, as well as the Leiningen plugins available during development.
cljstyle is used to automatically format all clojure(script) code at Wall Brew. Further, each application uses the same cljstyle configuration to maintain as consistent of a look and feel as possible. While the configuration is minimal, rebroadcasting the file minimizes the cost of any future extension or change.
clj-kondo is used as the primary linting too for clojure(script) code at Wall Brew. Aside from a few special rules and hooks, most applications and all libraries, are generally able to leverage the same linter configuration. The configuration is designed to cleanly integrate with code quality tools, and to push developers towards consistent coding standards.
Sealog is the default changelog management tool used at Wall Brew. All applications and libraries are able to leverage the same changelog configuration. The configuration is designed to enforce consistent Changelog and versioning standards.
Several community documents establish policies for all Wall Brew repositories. Since Github leverages these files on a per-repository basis to display contextual links and information; therefore, a full-text copy must exist locally.
All community members should have a clear and shared understanding of what is considered acceptable and unacceptable behavior. To prevent ad-hoc or just-in-time rule setting, we have explicitly outlined our expectations and rules in text. The Code of Conduct strives to meet three goals:
- Welcome contributors and participants
- Define basic standards and rules for community participation
- Outline procedures for handling abuse and violation of said rules and standards
Wall Brew maintains one standard policy for communicating repository and dependency vulnerabilities.
To streamline communication od sensitive and time-critical information, this files should be made uniformly available as SECURITY.md.
This also automatically populates the Security Advisory tab in Github.
Barring exception, all Wall Brew libraries are provided under the MIT License. Common convention, and the literal text of the MIT license, require that it is provided alongside any repository or piece of software covered by that license. Since it must contain the exact text of the license, we rebroadcast it undecorated without metadata/comments about this repository.
GitHub repositories allow owners to automatically assign Pull Request reviewers based off of impacted files in a CODEOWNERS file. Publicly available libraries are owned collectively by all members of the Wall Brew organization, and a basic configuration notifies us of Pull Requests more efficiently.
Contributor guidelines set explicit, upfront expectations around contributions to our open source repositories. This includes additional information about of the actions/requests that Wall Brew maintainers and automated entities may take, outline that all contributions must adhere to any applicable intellectual property laws, and outlines that all contributions must be made in good-faith adherence to the Code of Conduct.
Since most Wall Brew repositories are written in Clojure/Clojurescript, and we encourage tools to work out of the box with no to minimal configuration, our automated quality checks and tests can be shared across repositories. Additionally, these files allow us to specify common bug report, feature request, and pull request templates. These provide a uniform experience for developers across all of our repositories.
gitignore is used to automatically prevent the inclusion of unwanted files in Git. Projects often maintain these files to ignore binary artifacts, build tool logs, temporary files generated by the project and its core tools. Additionally, common development tools or operating system level files may be included too. Files generated during individual development generally should not be added to project gitignore files, and should be ignored at the user level.
Issue Templates prompt users for some basic information while raising GitHub issues. Since most of Wall Brew's public repositories are Clojure libraries, we often need the same information to diagnose issues and field requests. These markdown templates auto-format user provided reports, and streamline providing information to us.
While diagnosing issues or problems, we often need additional context or information to identify the root cause. This includes but is not limited to the consumer's Clojure version, the deployment/development environment, and the usage context. A template provides a proactive context in which this information may be provided.
Wall Brew's offerings are most commonly informed by our own development processed and needs; however, our end user may also identify their own needs. To request these additions to our offerings, we usually need additional information to understand their needs and desires. A template provides a proactive context in which this information may be provided.
To provide a consistent experience to developers contributing to Wall Brew repositories, we apply consistent CI/CD actions to as many repositories as possible. These include quality controls, like testing and linting, as well as development convenience tools, like automatic labelers and deployment tooling. Historically, these were manually synchronized between repositories.
Several of our GitHub actions automatically tag Pull Requests with labels useful for filtering lists. Creating these idempotently within actions causes the description and color setting sto be lost. While losing the label color is annoying, the description is used to render alt text for the badges displayed to represent each label. Therefore, it's critical to maintain the description for users that rely on alt text.
New contributors often need guidance or reminders on the manual steps in our change process. Additionally, we can prompt contributors to provide some high level information about their changes. For that reason, we use a standard Pull Request Template in each of our repositories.
It is just as important to denote which files are poor candidates for inclusion in rebroadcast
- GitHub Actions and development tools unique to individual repositories, such as the deployment tooling for the Brew Bot UI
- Files which are automatically generated as the result of development tools
This repo is not intended for outside revision; however, it is critical to note how we can update and support our internal offerings as well.
New files that will be replicated to several projects should be added within the sources folder.
That folder is segmented into several high-level groups, and new files should be added to their most relevant section.
For example, the community subfolder for documentation like our Security policy.
After adding the file, add a description of its value to the README.
Finally, add it to each repository in the sync configuration.
Information on that file's configuration may be found in the repo-file-sync-action repository.
WallBrewBot should automatically posses the correct access to each repository within the Wall Brew GitHub organization. To add a new repository, add it to the sync configuration and any files you wish to be synchronized to that repository. Information on that file's configuration may be found in the repo-file-sync-action repository.
Copyright © 2022-2024 - Wall Brew Co
This software is provided for free, public use as outlined in the MIT License