From e09e573d208a96790c2ab83ffacdb1ec897e93b9 Mon Sep 17 00:00:00 2001 From: NickChecan Date: Sat, 19 Oct 2024 02:47:03 +0000 Subject: [PATCH] docs: update readme with project info --- CONTRIBUTING.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..534394a --- /dev/null +++ b/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. \ No newline at end of file diff --git a/README.md b/README.md index c410fc2..dc998c5 100644 --- a/README.md +++ b/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) \ No newline at end of file +[![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= test//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).
+2. **Submit Pull Requests:** Fork the repository, create a new branch, make your changes, and submit a PR.
+3. **Improve Documentation:** Help us improve the README or add examples to make setup easier.
+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
+Licensed under the MIT License. See [LICENSE](LICENSE). \ No newline at end of file