Skip to content

Latest commit

 

History

History
201 lines (134 loc) · 8.23 KB

CONTRIBUTING.md

File metadata and controls

201 lines (134 loc) · 8.23 KB
Raw

Contributing to az-pim-cli

Welcome! We are glad that you want to contribute to our project! 💖

There are many ways to contribute:

Table of Contents

I Have a Question

If you want to ask a question, we assume that you have read the available README.

Before you ask a question, it is best to search for existing Issues that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.

If you then still feel the need to ask a question and need clarification, we recommend the following:

  • Create a post in the Discussions
  • Open an Issue.
  • Provide as much context as you can about what you're running into.
  • Provide project and platform versions (OS, golang version, etc), depending on what seems relevant.

I Want To Contribute

Reporting Bugs

Before Submitting a Bug Report

A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.

  • Make sure that you are using the latest version.
  • Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the README. If you are looking for support, you might want to check this section).
  • To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the issue tracker.

How Do I Submit a Good Bug Report?

You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to <>.

We use GitHub issues to track bugs and errors. If you run into an issue with the project:

Once it's filed, a maintainer will try to investigate the issue. Please make sure that you respond within reasonable time if there are any follow-up questions.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for az-pim-cli, including completely new features and minor improvements to existing functionality. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.

Before Submitting an Enhancement

  • Make sure that you are using the latest version.
  • Read the README carefully and find out if the functionality is already covered.
  • Perform a search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.

How Do I Submit a Good Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues.

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Make sure to fill out all of the required fields in the issue (following the template for feature requests).

Your First Code Contribution

In general, we follow the "fork-and-pull" Git workflow.

Here's a quick guide:

  1. Create your own fork of the repository
  2. Clone the forked project to your machine
  3. To keep track of the original repository, add another remote named 'upstream'
git remote add upstream [email protected]:netr0m/az-pim-cli.git
  1. Create a branch locally with a succinct but descriptive name and prefixed with change type.
git checkout -b feature/my-new-feature
  1. Make the changes in the newly created branch.
  2. Stage the changed files
git add path/to/filename
  1. Commit your changes; but make sure to follow our Styleguide for commit messages
git commit -m "<type>[optional scope]: <description>"
  1. Before you create the pull request, be sure to rebase onto the upstream source. This ensures your code is running on the latest available code.
git fetch upstream
git rebase upstream/main
  1. Push to your fork.
git push origin feature/my-new-feature
  1. Submit a pull request to the original repository (via the GitHub web interface)
  • Make sure that you have an issue associated to the change you wish to introduce, and reference the issue in the pull request

That's it... thank you for your contribution!

Automated checks

The GitHub repository includes a few workflows that will run on new pull requests. Make sure to resolve any issues if any of the tests are failing.

Code review process

The maintainer(s) will look try to review pull requests on a regular basis. After feedback has been given, we expect responses within reasonable time. If there is no response from the contributor, the pull request may be closed.

pre-commit

When contributing to this project, pre-commits are necessary, as they run certain checks, sanitisers, and formatters.

The project provides a .pre-commit-config.yaml file that is used to setup git pre-commit hooks.

On commit locally, code is automatically formatted and checked for security vulnerabilities using pre-commit git hooks.

Installation

To initialize pre-commit in your local repository, run

pre-commit install

This tells pre-commit to run for this repository on every commit.

Usage

Pre-commit will run on every commit, but can also be run manually on all files:

pre-commit run --all-files

Styleguides

Commit Messages

This repository defines precise rules for how the git commit messages may be formatted.

We enforce the conventional commits specification for commit messages, both through pre-commit hooks and through GitHub Actions workflows.

The commit messages should adhere to the following structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

where type must be one of feat, fix, refactor, chore, test, ci, build, lint, docs

For instance,

Changes to the documentation

docs: correct spelling of CHANGELOG

A breaking change introducing a new feature

feat!: list eligible roles

Summary should:

  • Be written in imperative, present tense, e.g. write add instead of added or adds.
  • Don't capitalize the first letter.
  • Don't write dot (.) at the end.
git commit -m "fix(parser): fix broken config parser"

git commit -m "feat(parser): add config file parser"

git commit -m "feat(new-parser): change to config-parser-lib
BREAKING CHANGE: new library does not support foo-construct"

This results in more readable messages that are easy to follow when looking through the project history, and faciliates for automated changelog generation.