Skip to content

Commit ba5f8dc

Browse files
dinushchathuryadinushchathurya
committed
📚 Create CONTRIBUTING.md file required instructions
1 parent f7eea76 commit ba5f8dc

File tree

1 file changed

+380
-0
lines changed

1 file changed

+380
-0
lines changed

‎docs/CONTRIBUTING.md‎

Lines changed: 380 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,380 @@
1+
# Contributing to EKS Helm Client GitHub Action
2+
3+
First off, thank you for considering contributing to the EKS Helm Client GitHub Action! It's people like you that make this tool better for everyone in the community.
4+
5+
## Table of Contents
6+
7+
- [Code of Conduct](#code-of-conduct)
8+
- [Getting Started](#getting-started)
9+
- [How Can I Contribute?](#how-can-i-contribute)
10+
- [Reporting Bugs](#reporting-bugs)
11+
- [Suggesting Enhancements](#suggesting-enhancements)
12+
- [Your First Code Contribution](#your-first-code-contribution)
13+
- [Pull Requests](#pull-requests)
14+
- [Development Setup](#development-setup)
15+
- [Style Guides](#style-guides)
16+
- [Git Commit Messages](#git-commit-messages)
17+
- [Bash Style Guide](#bash-style-guide)
18+
- [Documentation Style Guide](#documentation-style-guide)
19+
- [Testing](#testing)
20+
- [Security](#security)
21+
- [Community](#community)
22+
23+
## Code of Conduct
24+
25+
This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [dinushchathurya21@gmail.com](mailto:dinushchathurya21@gmail.com).
26+
27+
## Getting Started
28+
29+
Before you begin:
30+
- Have you read the [Code of Conduct](CODE_OF_CONDUCT.md)?
31+
- Check out the [existing issues](https://github.com/open-source-srilanka/eks-helm-client-github-action/issues)
32+
- Read the [README](../README.md) and [documentation](../docs/)
33+
34+
## How Can I Contribute?
35+
36+
### Reporting Bugs
37+
38+
Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible using the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md).
39+
40+
**Great Bug Reports** tend to have:
41+
- A quick summary and/or background
42+
- Steps to reproduce
43+
- Be specific!
44+
- Give sample code if you can
45+
- What you expected would happen
46+
- What actually happens
47+
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
48+
49+
### Suggesting Enhancements
50+
51+
This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality.
52+
53+
Before creating enhancement suggestions, please check the existing issues and discussions. When you are creating an enhancement suggestion, please include as many details as possible using the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md).
54+
55+
**Great Enhancement Suggestions** tend to have:
56+
- A clear use case
57+
- An explanation of how it would benefit other users
58+
- If possible, example usage or mockups
59+
60+
### Your First Code Contribution
61+
62+
Unsure where to begin contributing? You can start by looking through these beginner and help-wanted issues:
63+
64+
- [Beginner issues](https://github.com/open-source-srilanka/eks-helm-client-github-action/labels/good%20first%20issue) - issues which should only require a few lines of code, and a test or two
65+
- [Help wanted issues](https://github.com/open-source-srilanka/eks-helm-client-github-action/labels/help%20wanted) - issues which should be a bit more involved than beginner issues
66+
67+
### Pull Requests
68+
69+
The process described here has several goals:
70+
- Maintain the project's quality
71+
- Fix problems that are important to users
72+
- Engage the community in working toward the best possible EKS Helm Client
73+
- Enable a sustainable system for maintainers to review contributions
74+
75+
Please follow these steps to have your contribution considered by the maintainers:
76+
77+
1. Follow all instructions in [the template](.github/PULL_REQUEST_TEMPLATE.md)
78+
2. Follow the [style guides](#style-guides)
79+
3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing
80+
81+
## Development Setup
82+
83+
1. **Fork and Clone the Repository**
84+
```bash
85+
git clone https://github.com/your-username/eks-helm-client-github-action.git
86+
cd eks-helm-client-github-action
87+
```
88+
89+
2. **Create a Feature Branch**
90+
```bash
91+
git checkout -b feature/your-feature-name
92+
```
93+
94+
3. **Set Up Development Environment**
95+
```bash
96+
# Make scripts executable
97+
chmod +x scripts/*.sh
98+
chmod +x .github/scripts/**/*.sh
99+
100+
# Install development dependencies (if any)
101+
# Currently, this action uses Docker, so ensure Docker is installed
102+
```
103+
104+
4. **Build the Docker Image**
105+
```bash
106+
docker build -t eks-helm-client:dev .
107+
```
108+
109+
5. **Run Tests**
110+
```bash
111+
# Unit tests
112+
./tests/unit/test-entrypoint.sh
113+
./tests/unit/test-health-check.sh
114+
./tests/unit/test-templates.sh
115+
116+
# Integration tests
117+
./.github/scripts/testing/run-integration-tests.sh
118+
```
119+
120+
## Style Guides
121+
122+
### Git Commit Messages
123+
124+
- Use the present tense ("Add feature" not "Added feature")
125+
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
126+
- Limit the first line to 72 characters or less
127+
- Reference issues and pull requests liberally after the first line
128+
- Use conventional commits format when possible:
129+
- `feat:` for new features
130+
- `fix:` for bug fixes
131+
- `docs:` for documentation changes
132+
- `style:` for formatting, missing semicolons, etc
133+
- `refactor:` for code refactoring
134+
- `test:` for adding missing tests
135+
- `chore:` for maintenance tasks
136+
137+
Example:
138+
```
139+
feat: add support for private Helm registries
140+
141+
- Add authentication for Harbor, Nexus, and Artifactory
142+
- Support both basic auth and token-based auth
143+
- Add comprehensive error handling for registry failures
144+
145+
Fixes #123
146+
```
147+
148+
### Bash Style Guide
149+
150+
We follow the [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) with some modifications:
151+
152+
#### Key Points:
153+
154+
1. **Shebang**
155+
```bash
156+
#!/bin/bash
157+
```
158+
159+
2. **Error Handling**
160+
```bash
161+
set -e # Exit on error
162+
set -u # Exit on undefined variable (when appropriate)
163+
set -o pipefail # Fail on pipe errors
164+
```
165+
166+
3. **Functions**
167+
```bash
168+
# Good
169+
function_name() {
170+
local var_name="$1"
171+
local another_var="${2:-default}"
172+
173+
# Function body
174+
echo "Processing: $var_name"
175+
}
176+
177+
# Usage
178+
function_name "argument" "optional"
179+
```
180+
181+
4. **Variables**
182+
```bash
183+
# Constants (readonly)
184+
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
185+
readonly DEFAULT_TIMEOUT=300
186+
187+
# Local variables
188+
local file_path="/tmp/test"
189+
190+
# Global variables (avoid when possible)
191+
GLOBAL_STATE="active"
192+
```
193+
194+
5. **Conditionals**
195+
```bash
196+
# Good
197+
if [[ -n "${variable:-}" ]]; then
198+
echo "Variable is set"
199+
fi
200+
201+
# Check file existence
202+
if [[ -f "$file_path" ]]; then
203+
echo "File exists"
204+
fi
205+
```
206+
207+
6. **Logging**
208+
```bash
209+
log_info() {
210+
echo -e "${BLUE}[INFO]${NC} $1" >&2
211+
}
212+
213+
log_error() {
214+
echo -e "${RED}[ERROR]${NC} $1" >&2
215+
}
216+
```
217+
218+
7. **Error Messages**
219+
```bash
220+
if [[ -z "${CLUSTER_NAME:-}" ]]; then
221+
log_error "CLUSTER_NAME is required"
222+
log_error "Please provide either:"
223+
log_error " - Input parameter: cluster-name"
224+
log_error " - Environment variable: CLUSTER_NAME"
225+
exit 1
226+
fi
227+
```
228+
229+
### Documentation Style Guide
230+
231+
1. **Markdown Files**
232+
- Use ATX-style headers (`#` not underlines)
233+
- Include a table of contents for long documents
234+
- Use code blocks with language specification
235+
- Include examples whenever possible
236+
237+
2. **Code Comments**
238+
```bash
239+
# Function to configure EKS cluster access
240+
# This function retrieves cluster information from AWS EKS API
241+
# and generates a kubeconfig file for authentication
242+
configure_eks_access() {
243+
# Implementation
244+
}
245+
```
246+
247+
3. **README Sections**
248+
- Keep examples concise and realistic
249+
- Include both basic and advanced usage
250+
- Provide troubleshooting guidance
251+
252+
## Testing
253+
254+
### Running Tests Locally
255+
256+
1. **Unit Tests**
257+
```bash
258+
# Run all unit tests
259+
for test in tests/unit/test-*.sh; do
260+
bash "$test"
261+
done
262+
```
263+
264+
2. **Integration Tests**
265+
```bash
266+
# Build the Docker image
267+
docker build -t eks-helm-client:test .
268+
269+
# Run integration tests
270+
./.github/scripts/testing/run-integration-tests.sh
271+
```
272+
273+
3. **Manual Testing**
274+
```bash
275+
# Test with dry run
276+
docker run --rm \
277+
-e INPUT_CLUSTER_NAME="test-cluster" \
278+
-e INPUT_REGION="us-west-2" \
279+
-e INPUT_DRY_RUN="true" \
280+
-e INPUT_ARGS="helm list" \
281+
eks-helm-client:test
282+
```
283+
284+
### Writing Tests
285+
286+
When adding new features, please include:
287+
288+
1. **Unit tests** for individual functions
289+
2. **Integration tests** for end-to-end scenarios
290+
3. **Documentation** with examples
291+
4. **Error cases** to ensure proper error handling
292+
293+
Example test structure:
294+
```bash
295+
#!/bin/bash
296+
# tests/unit/test-new-feature.sh
297+
298+
source "$(dirname "$0")/../../.github/scripts/testing/utils.sh"
299+
300+
test_new_feature() {
301+
# Test implementation
302+
local result
303+
result=$(new_feature "input")
304+
305+
if [[ "$result" == "expected" ]]; then
306+
log_test_result "PASS" "New feature test"
307+
return 0
308+
else
309+
log_test_result "FAIL" "New feature test" "Expected 'expected', got '$result'"
310+
return 1
311+
fi
312+
}
313+
314+
# Run test
315+
test_new_feature
316+
```
317+
318+
## Security
319+
320+
### Security Considerations
321+
322+
1. **Never commit secrets** or sensitive data
323+
2. **Validate all inputs** to prevent injection attacks
324+
3. **Use secure defaults** for all configurations
325+
4. **Follow the principle of least privilege** for IAM permissions
326+
5. **Clean up sensitive data** after use
327+
328+
### Reporting Security Issues
329+
330+
Please **DO NOT** create public GitHub issues for security vulnerabilities. Instead, please report them directly to [dinushchathurya21@gmail.com](mailto:dinushchathurya21@gmail.com).
331+
332+
## Community
333+
334+
### Getting Help
335+
336+
- 📧 Email: [dinushchathurya21@gmail.com](mailto:dinushchathurya21@gmail.com)
337+
- 💬 Discussions: [GitHub Discussions](https://github.com/open-source-srilanka/eks-helm-client-github-action/discussions)
338+
- 🐛 Issues: [GitHub Issues](https://github.com/open-source-srilanka/eks-helm-client-github-action/issues)
339+
340+
### Project Structure
341+
342+
```
343+
eks-helm-client-github-action/
344+
├── .github/ # GitHub-specific files
345+
│ ├── workflows/ # CI/CD workflows
346+
│ └── scripts/ # CI/CD scripts
347+
├── docs/ # Documentation
348+
│ └── examples/ # Usage examples
349+
├── scripts/ # Main action scripts
350+
├── templates/ # Configuration templates
351+
├── tests/ # Test files
352+
│ ├── unit/ # Unit tests
353+
│ └── integration/ # Integration tests
354+
├── action.yml # Action definition
355+
├── Dockerfile # Container definition
356+
└── README.md # Main documentation
357+
```
358+
359+
### Release Process
360+
361+
1. **Version Numbering**: We use [Semantic Versioning](https://semver.org/)
362+
2. **Release Branches**: Create from `main` branch
363+
3. **Testing**: All tests must pass
364+
4. **Documentation**: Update CHANGELOG.md
365+
5. **Tag**: Create version tag (e.g., `v2.1.0`)
366+
367+
### Recognition
368+
369+
Contributors will be recognized in:
370+
- The project README
371+
- Release notes
372+
- Special thanks in major releases
373+
374+
## Thank You!
375+
376+
Your contributions to open source make great things possible. Thank you for taking the time to contribute to the EKS Helm Client GitHub Action!
377+
378+
---
379+
380+
**Made with ❤️ by the Open Source Sri Lanka community**

0 commit comments

Comments
 (0)