Merge pull request #16 from The-Nefarious-Developer/documentation

docs: update readme with project info

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to this Project
+
+Thank you for considering contributing to this project! Your contributions are greatly appreciated and help us improve and evolve. Below are some guidelines to follow when contributing.
+
+- [Code of conduct](#code-of-conduct)
+- [How to contribute](#how-to-contribute)
+- [Using the issue tracker](#using-the-issue-tracker)
+- [Code Quality and Testing](#code-quality-and-testing)
+- [Getting Your Pull Request Merged](#getting-your-pull-request-merged)
+
+## Code of conduct
+
+Help us keep this project open and inclusive. Please read and follow our [Code of conduct](CODE_OF_CONDUCT.md).
+
+## How to Contribute
+
+1. **Fork the Repository**: Start by forking the repository on GitHub.
+2. **Create a Branch**: Make a feature branch to work on.
+3. **Make Your Changes**: Ensure you make clear, focused commits for each change.
+4. **Submit a Pull Request**: When you're ready, submit a pull request (PR) with a detailed description of what your changes accomplish.
+
+## Commit Message Guidelines
+
+We follow the **Angular Semantic Release** pattern for commit messages. This ensures clear and structured commit history, which helps in understanding the purpose of changes and generating changelogs. 
+
+### Commit Message Format
+
+Each commit message should include a type and a description.
+
+### Allowed Types
+
+The type must be one of the following:
+
+| Type         | Description                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| **feat**     | A new feature (this triggers a new version release).                                                     |
+| **fix**      | A bug fix.                                                                                               |
+| **docs**     | Documentation-only changes.                                                                              |
+| **style**    | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.). |
+| **refactor** | A code change that neither fixes a bug nor adds a feature.                                               |
+| **test**     | Adding missing or correcting existing tests.                                                             |
+| **chore**    | Changes to the build process or auxiliary tools and libraries such as documentation generation.          |
+| **try**      | Operation that needs to be tested through an unconventional method (pipeline and others)                 |
+
+
+Adding a new feature is highly recommended as it contributes significantly to the project's growth.
+
+### Atomic commits
+
+If possible, make [atomic commits](https://en.wikipedia.org/wiki/Atomic_commit), which means:
+
+- a commit should contain exactly one self-contained functional change
+- a functional change should be contained in exactly one commit
+- a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature without documentation, etc...)
+
+A complex feature can be broken down into multiple commits as long as each one maintains a consistent state and consists of a self-contained change.
+
+## Using the Issue Tracker
+
+We encourage contributors to use the issue tracker for all suggestions, feature requests, and bug reports. When you submit a PR, reference any related issue to give context.
+
+- **Feature Requests**: If you have a new idea or enhancement, feel free to create an issue labeled as "feature request".
+- **Bug Reports**: If you've encountered a bug, please submit an issue with as much detail as possible.
+
+## Code Quality and Testing
+
+- **Tests are Mandatory**: All changes must be accompanied by relevant tests. Contributions without tests will not be accepted.
+- **Linting**: Ensure that your code adheres to the project's linting rules. PRs should not introduce any linting errors.
+
+## Getting Your Pull Request Merged
+
+1. Ensure that all tests are passing.
+2. Make sure your code doesn't introduce any linting errors.
+3. Ensure your commit messages follow the guidelines mentioned above.
+4. Include updates to documentation if necessary.
+
+---
+
+Thank you for taking the time to read this! We look forward to your contributions.

README.md

@@ -3,4 +3,77 @@
 [![Release Devcontainer Templates](https://github.com/The-Nefarious-Developer/devcontainer-templates/actions/workflows/release.yaml/badge.svg)](https://github.com/The-Nefarious-Developer/devcontainer-templates/actions/workflows/release.yaml)
 [![Update Documentation](https://github.com/The-Nefarious-Developer/devcontainer-templates/actions/workflows/update-documentation.yaml/badge.svg)](https://github.com/The-Nefarious-Developer/devcontainer-templates/actions/workflows/update-documentation.yaml)
 [![Test Latest Updated Templates](https://github.com/The-Nefarious-Developer/devcontainer-templates/actions/workflows/test-pr.yaml/badge.svg)](https://github.com/The-Nefarious-Developer/devcontainer-templates/actions/workflows/test-pr.yaml)
-[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+
+ This repository provides a set of ready-to-use devcontainer templates that you can integrate directly into your Visual Studio Code environment. These templates are particularly useful for SAP developers who want to set up a consistent development environment across different projects without hassle.
+
+> The docker containers published through this project can be found at the the [`devcontainer-images`](https://github.com/The-Nefarious-Developer/devcontainer-images) repository. 
+
+## Available Templates
+
+Ths repository generates the following devcontainer templates:
+
+| Template                  | Image                                                                                                                                                                            |
+|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| sap-cap-javascript-node   | [ghcr.io/the-nefarious-developer/sap-cap-javascript-node:{VERSION TAG}](https://github.com/The-Nefarious-Developer/devcontainer-images/pkgs/container/sap-cap-javascript-node)   |
+
+## Content
+
+- [`src`](src) - Contains reusable dev container templates.
+- [`test`](test) - Contains the test suite for each provided template.
+
+## Prerequisites
+
+To use the devcontainer templates provided in this repository, you will need:
+
+- [Docker](https://www.docker.com/get-started) installed on your system.
+- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+
+## How it works
+
+The directories inside the [`src`](src) folder will contain the files that will compose the templates to be created. 
+
+Each template folder will have the following structure:
+- **.devcontainer**: Folder which is going to contain the `devcontainer.json` with properties, dependencies and the container image to be referenced by the template. 
+- **devcontainer-template.json** Configuration file that define key metadata and attributes for the container environment.
+
+Whenever a change in the template happens, the `update-documentation.yaml` pipeline will be triggered and a new pull request will be created to update the `README.md` file inside each template directory. This new document will be composed by metadata defined in the `devcontainer-template.json` and the content described in the `NOTES.md` file. 
+
+## Testing
+
+Each template needs to have a test implementation. The testing operations in this project follows the harness test strategy applied at their own [container images](https://github.com/The-Nefarious-Developer/devcontainer-images), which can be leveraged in case of new template implementations.
+
+> **Note:** The lack of test implementation might cause the CI/CD pipeline to fail.
+
+### Testing locally
+
+To test the images locally, the environment variable `VARIANT` need to be set prior to the bash file execution.
+
+Template for command to run the test locally:
+
+```
+VARIANT=<upstream version> test/<image>/test.sh
+```
+
+The [`package.json`](package.json) file contains an example of local testing through the script `test:local`.
+
+## How can I contribute?
+
+Contributions are welcome! Here's how you can get involved:
+
+1. **Report Issues:** Found a bug or have a feature request? [Open an issue](https://github.com/The-Nefarious-Developer/devcontainer-images/issues). <br />
+2. **Submit Pull Requests:** Fork the repository, create a new branch, make your changes, and submit a PR. <br />
+3. **Improve Documentation:** Help us improve the README or add examples to make setup easier. <br />
+4. **Test & Feedback:** Try the devcontainer images and give us feedback to improve them.
+
+Please follow the [contribution guidelines](CONTRIBUTING.md) for more details.
+
+## References
+
+The development container images used by these templates can be found at [devcontainer-images](https://github.com/The-Nefarious-Developer/devcontainer-images) repository.
+
+These templates were created following the guidelines provided through the [devcontainers/template-starter](https://github.com/devcontainers/template-starter) and [devcontainers/templates](https://github.com/devcontainers/templates).
+
+## License
+Copyright (c) 2024 The Nefarious Developer <br />
+Licensed under the MIT License. See [LICENSE](LICENSE).