Contributing

April 13, 2023 · View on GitHub

Thank you for contributing. Contributions are always welcome, no matter how large or small.

Guidelines
Pull Requests
Coding Rules
Working with Code
File Structure

Guidelines

As a contributor, here are the guidelines you should follow:

Code of conduct
How can I contribute?
Using the issue tracker
Submitting a Pull Request
Coding rules
Working with code

We also recommend to read How to Contribute to Open Source.

Code of conduct

Please read and follow our code of conduct.

How can I contribute?

Improve documentation

Consider helping us to improve our documentation by finding documentation issues that need help, and by submitting pull requests for corrections, clarifications, more examples, new features, etc.

Please follow the Documentation guidelines.

Give feedback on issues

Some issues are created without information requested in the Bug report guideline. Help making them easier to resolve by adding any relevant information.

Issues with the type: discussion label are meant to discuss the implementation of new features. Participating in the discussion is a good opportunity to get involved and influence the future.

Fix bugs and implement features

Confirmed bug and ready to implement features are marked with the help label. Post a comment on an issue to indicate you would like to work on it and to request help from the team and the community.

Using the issue tracker

The issue tracker is the channel for bug reports, features requests and submitting pull requests only. Please use the Support and Get help sections for support, troubleshooting and questions.

Before opening an Issue or a Pull Request, please use the GitHub issue search to make the bug or feature request hasn't been already reported or fixed.

Bug report

A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report and fill the information requested in the Bug/Issue Template.

Feature request

Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible and fill the information requested in the Agile Story Template.

Submitting a Pull Request

Good pull requests whether patches, improvements or new features are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

Please ask first before embarking on any significant pull request (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

If you never created a pull request before, then learn how to submit a pull request (great tutorial).

Here is a summary of the steps to follow:

Set up the workspace
If you cloned a while ago, get the latest changes from upstream and update dependencies.
Create a new topic branch (off the main project development branch) to contain your feature, change, or fix; git checkout -b <topic-branch-name>
Make your code changes, following the Coding rules
Push your topic branch up to your fork; git push origin <topic-branch-name>
Open a Pull Request with a clear title and description.

Tips:

Create your branch from main.
Ensure your git commit messages follow the required format.
Ensure your scripts are well-formed, well-documented and object-oriented.
Ensure your scripts are stateless and can be reused by all.
Update your branch, and resolve any conflicts, before making pull request.
Fill in the PR template.
Do not include issue numbers in the PR title.
Include screenshots and animated GIFs in your pull request whenever possible.
Follow the style guide applicable to the language or task.
Include thoughtfully-worded, well-structured tests/specs. See the Tests/Specs Style Guide.
Document new code based on the Documentation Style Guide.
End all files with a newline.

git clone git@github.com:seantrane/engineering.git engineering && cd engineering

Install the repo dependencies

./run install

File Structure

engineering/
├─ .github/                                    * Repository configuration directory
│  ├─ ISSUE_TEMPLATE/                          * Templates available when creating an issue
│  │  ├─ issue_template.sh                     * Default issue template
│  │  ├─ [name]_template.sh                    * An issue template
│  │  :
│  │
│  ├─ linters/                                 * Directory for linter configuration files
│  │  ├─ .markdown-lint.yml                    * Markdown-lint config
│  │  ├─ .sass-lint.yml                        * SASS-lint config
│  │  ├─ .tflint.hcl                           * Terraform-lint config
│  │  ├─ .yaml-lint.yml                        * YAML-lint config
│  │  :
│  │
│  ├─ PULL_REQUEST_TEMPLATE/                   * Templates available when creating a pull request
│  │  ├─ pull_request_template.sh              * Default pull request template
│  │  ├─ [name]_template.sh                    * A pull request template
│  │  :
│  │
│  ├─ workflows/                               * Directory for GitHub Actions Workflows
│  │  ├─ delivery.yml                          * Continuous Delivery Workflow
│  │  ├─ deployment.yml                        * Continuous Deployment Workflow
│  │  ├─ integration.yml                       * Continuous Integration Workflow
│  │  ├─ maintenance.yml                       * Maintenance Workflow
│  │  :
│  │
|  ├─ dependabot.yml                           * Dependabot config
|  ├─ labels.json                              * GitHub Labels config
|  ├─ reaction.yml                             * action-reaction config
|  ├─ stale.yml                                * action-stale config
|  └─ super-linter.env                         * Shell support tests
│
├─ bin/                                        * Shell binaries directory
│  └─ [function_name]                          * Shell binaries (typically mapped to respective functions)
│
├─ scripts/                                    * shell scripts directory
│  ├─ functions/                               * Shell functions directory
│  │  ├─ [function_name].sh                    * Shell function (with filename identical to function name)
│  │  :
│  │
|  ├─ load_functions.sh                        * Shell functions (loads all `./scripts/functions/*`)
|  └─ test.sh                                  * Shell support tests
│
├─ .editorconfig                               * keep developers/IDE's in sync
├─ .env.example                                * environment configuration variables template
├─ .gitignore                                  * ignore files for git
├─ CHANGELOG.md                                * changelog autogenerated by `@semantic-release/changelog`
├─ CODE_OF_CONDUCT.md                          * Code of conduct policy
├─ CODEOWNERS                                  * default pull-request reviewers
├─ CONTRIBUTING.md                             * contributing guidelines
├─ docker-compose.yml                          * Docker-compose config
├─ README.md                                   * repository readme
├─ run                                         * Shell script endpoint for running repo shell functions, binaries
├─ sonar-project.properties                    * SonarQube/SonarCloud configuration
└─ STYLE_GUIDES.md                             * Style guides, standards and practices

Contributing

Table of Contents