Project documentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# [Examples uses GitHub's Code of Conduct](https://docs.github.com/en/site-policy/github-terms/github-community-code-of-conduct)
+
+## [Reporting abuse or spam](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam)

CODING_STANDARDS.md

@@ -0,0 +1,22 @@
+# [Contracts uses Googles Style Guide](https://google.github.io/styleguide/javaguide.html)
+
+## With the following deviations
+### Arrangement:
+#### 1. The most accessible stuff is at the top.
+    @Override
+    public void doSomePublicallyDelaredAction() {
+    }
+#### 2. When possible all code is ordered by accessibility.
+    public
+    protected 
+    package
+    private
+#### 3. Public static final fields at the top.
+    public static final String APPLICATION_NAME = "MyApp";
+#### 4. All other fields should be private and at the bottom. Create accessors methods instead.
+    // the last thing someone needs to know are the 
+    // implementation fields used to implement a feature
+
+    private final CountDownLatch thresholdLatch;
+    private final Map<String,String> cache;
+#### 5. If Java allowed imports at the bottom, I would require it :)

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to Examples
+
+Thank you for your interest in contributing to Examples! We welcome and value all contributions, from new features to bug fixes and documentation improvements. This guide will help you navigate the process.
+
+Please note that this project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## Table of Contents
+1.  [Reporting Bugs](#reporting-bugs)
+2.  [Suggesting Enhancements](#suggesting-enhancements)
+3.  [Setting up Your Development Environment](#setting-up-your-development-environment)
+4.  [Submitting a Pull Request](#submitting-a-pull-request)
+5.  [Improving the Documentation](#improving-the-documentation)
+6.  [Commit Message Styleguide](#commit-message-styleguide)
+7.  [Need Help?](#need-help)
+
+## 1. Reporting Bugs
+We use [GitHub Issues](https://github.com/jonloucks/examples/issues) to track bugs. Before creating a new issue, please check the existing issues to ensure the bug has not already been reported.
+
+When submitting a [bug report](https://github.com/jonloucks/examples/issues/new), please provide the following information:
+-   **Clear and concise title:** A brief summary of the issue.
+-   **Steps to reproduce:** Explain the steps to reproduce the behavior.
+-   **Expected behavior:** Describe what you expected to happen.
+-   **Actual behavior:** Describe what actually happened, including any error messages.
+-   **Context:** Include your operating system, software version, and any relevant logs or screenshots.
+
+## 2. Suggesting Enhancements
+For suggesting enhancements or new features, please [open a GitHub Issue]((https://github.com/jonloucks/examples/issues/new)) and follow these guidelines:
+-   **Use a descriptive title:** Identify the suggestion clearly.
+-   **Describe the enhancement:** Explain the feature in as much detail as possible, including its use case and why it would be valuable.
+-   **Check existing suggestions:** Search for similar ideas in the existing issues. If a similar suggestion exists, add your support or additional context there.
+
+## 3. Setting up Your Development Environment
+To get started with local development:
+1.  **Fork the repository** to your own GitHub account.
+2.  **Clone your forked repository** to your local machine:
+    ```sh
+    git clone https://github.com/jonloucks/examples.git
+    ```
+3.  **Install dependencies**:
+    ```sh
+    # To build a JDK it is recommended ot use at least 17
+    javac --version
+    ```
+4.  **Run tests** to ensure everything is working correctly:
+    ```sh
+    ./gradlew test
+    ```
+
+## 4. Submitting a Pull Request
+Before submitting a pull request (PR), please follow these steps:
+-   **Create a new branch** from the `main` branch with a descriptive name (e.g., `feature/add-new-feature` or `fix/issue-description`).
+-   **Ensure your code is well-tested** and passes all existing tests with minimum coverage of 95% 
+-   **Write a clear and detailed commit message** following the style guide below.
+-   **Push your changes** to your forked repository and open a PR against our `main` branch.
+-   **Fill out the PR template** completely.
+
+## 5. Improving the Documentation
+Documentation is vital for any project. If you find a typo, unclear explanation, or want to add a new section, please submit a PR with your changes. All documentation is located in the `docs/` folder.
+
+## 6. Commit Message Styleguide
+We use a conventional commit style for our commit messages to maintain a readable and organized history. A commit message should be structured as follows:
+### 1. Subject Line:
+   Conciseness: Limit the subject line to around 50-72 characters. This encourages a brief, impactful summary and ensures readability in various Git tools.
+   Imperative Mood: Use the imperative mood (e.g., "Fix bug," "Add feature," "Update documentation") as if you are giving a command. This aligns with Git's own generated messages (like git merge).
+   Capitalization: Capitalize the first letter of the subject line.
+   No Period: Do not end the subject line with a period.
+   Keywords (Optional): Consider using keywords like "feat," "fix," "chore," "docs," "style," "refactor," "test" at the beginning, especially if following a Conventional Commits specification.
+### 2. Body:
+   Blank Line Separation: Separate the subject line from the body with a single blank line. This is crucial for Git tools to correctly parse the message.
+   Detailed Explanation: Provide a more in-depth explanation of what the change does and why it was made. Focus on the motivation and the problem it solves, rather than simply reiterating how it was implemented (which is evident in the code itself).
+   Line Wrapping: Wrap the body text at approximately 72 characters to maintain readability in terminal environments.
+   Bullet Points (Optional): Use bullet points or lists for better organization and clarity when describing multiple aspects of the change.
+   Issue References (Optional): If the commit addresses a specific issue or bug, reference its identifier (e.g., "Closes #123," "Fixes BUG-456").
+   Breaking Changes (Optional): Clearly indicate any breaking changes, often by starting a new section in the body or footer with "BREAKING CHANGE:".
+

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,36 @@
+# Pull Request Title (e.g., feature: Add user authentication, fix: Resolve login bug)
+
+## Description
+
+[Provide a clear and concise description of the changes introduced by this PR. Explain *what* was changed and *why* it was changed. Link to any related issues or tasks using keywords like `Closes #123` or `Fixes #456`.]
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Refactor (code improvement or restructuring without changing external behavior)
+- [ ] Documentation update
+- [ ] Chore (e.g., dependency updates, build tooling changes)
+
+## How Has This Been Tested?
+
+[Describe the testing you have performed to ensure the changes work as expected. Include details about:
+- Unit tests
+- Integration tests
+- Manual testing steps (if applicable, provide specific instructions for reviewers to verify the changes)
+- Screenshots or GIFs (if relevant, especially for UI changes)]
+
+## Checklist:
+
+- [ ] My code follows the project's coding style guidelines.
+- [ ] I have performed a self-review of my own code.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] I have made corresponding changes to the documentation (if necessary).
+- [ ] My changes generate no new warnings.
+- [ ] I have added tests that prove my fix is effective or my feature works.
+- [ ] New and existing unit tests pass locally with my changes.
+
+## Additional Notes
+
+[Add any other relevant information for the reviewers, such as potential performance impacts, known limitations, or alternative solutions considered during development.]

README.md

@@ -0,0 +1,14 @@
+# examples
+Examples for suite of projects 
+
+### Provide useful examples to help with adoption and understanding.
+
+Examples of dependency inversion, Dependency injection, Inversion of Control,
+ Solid Principles: Single responsibility, Open-closed, Liskov substitution, Interface segregation, Dependency inversion.
+ OpenSSF Best Practices. Java Module Support. Strong data encapsulation.
+```
+```
+
+## Goals
+Provide useful examples to help with adoption and understanding.
+

SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+We take security seriously and appreciate prompt reports of vulnerabilities. If you discover a security vulnerability within this project, please report it to us as soon as possible.
+
+**How to report:**
+
+*   **Create Advisory:** https://github.com/jonloucks/examples/security/advisories/new
+
+**Please do not disclose the vulnerability publicly until we have had a chance to address it.**
+
+## Our Response Timeline
+
+We aim to acknowledge all vulnerability reports within 2 business days. Our team will then investigate the report and provide updates on the remediation progress. The time to resolution will depend on the severity and complexity of the vulnerability.
+
+## Responsible Disclosure Guidelines
+
+We ask that you follow these guidelines for responsible disclosure:
+
+1.  **Do not exploit the vulnerability:** Do not attempt to gain unauthorized access, modify data, or disrupt services.
+2.  **Do not disclose publicly:** Keep the vulnerability confidential until we have confirmed a fix and given permission for public disclosure.
+3.  **Provide sufficient details:** Help us understand and reproduce the vulnerability by providing clear and comprehensive information.
+4.  **Cooperate with us:** Be available to answer questions and provide further details as needed during the investigation.
+
+## Supported Versions
+
+Only the latest stable release of this project is actively supported for security updates. While we may address critical vulnerabilities in older versions, we recommend upgrading to the latest stable release for the best security posture.
+
+**Currently Supported Version:**
+
+# Security Policy
+
+## Supported Versions
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.0.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Tell them where to go, how often they can expect to get an update on a
+reported vulnerability, what to expect if the vulnerability is accepted or
+declined, etc.

STYLE_GUIDE.md

@@ -0,0 +1,22 @@
+# [Examples uses Googles Style Guide](https://google.github.io/styleguide/javaguide.html)
+
+## With the following deviations
+### Arrangement:
+#### 1. The most accessible stuff is at the top.
+    @Override
+    public void doSomePublicallyDelaredAction() {
+    }
+#### 2. When possible all code is ordered by accessibility. 
+    public
+    protected 
+    package
+    private
+#### 3. Public static final fields at the top.
+    public static final String APPLICATION_NAME = "MyApp";
+#### 4. All other fields should be private and at the bottom. Create accessors methods instead.
+    // the last thing someone needs to know are the 
+    // implementation fields used to implement a feature
+
+    private final CountDownLatch thresholdLatch;
+    private final Map<String,String> cache;
+#### 5. If Java allowed imports at the bottom, I would require it :)