Skip to content

Commit f4c4350

Browse files
harshavardhanaharshavardhana
committed
update all missing docs
1 parent af6dc51 commit f4c4350

17 files changed

+2466
-1501
lines changed

‎CLAUDE.md‎

Lines changed: 70 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
1-
# CLAUDE.md
1+
CLAUDE.md
2+
=========
23

34
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
45

5-
## Commands
6+
Commands
7+
--------
68

79
### Testing
10+
811
```bash
912
# Run all tests with race detection (requires MinIO server at localhost:9000)
1013
SERVER_ENDPOINT=localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin ENABLE_HTTPS=1 MINT_MODE=full go test -race -v ./...
@@ -24,6 +27,7 @@ SERVER_ENDPOINT=localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin ENABL
2427
```
2528

2629
### Linting and Code Quality
30+
2731
```bash
2832
# Run all checks (lint, vet, test, examples, functional tests)
2933
make checks
@@ -39,6 +43,7 @@ golangci-lint run --timeout=5m --config ./.golangci.yml
3943
```
4044

4145
### Building Examples
46+
4247
```bash
4348
# Build all examples
4449
make examples
@@ -47,64 +52,74 @@ make examples
4752
cd examples/s3 && go build -mod=mod putobject.go
4853
```
4954

50-
## Architecture
55+
Architecture
56+
------------
5157

5258
### Core Client Structure
59+
5360
The MinIO Go SDK is organized around a central `Client` struct (api.go:52) that implements Amazon S3 compatible methods. Key architectural patterns:
5461

55-
1. **Modular API Organization**: API methods are split into logical files:
56-
- `api-bucket-*.go`: Bucket operations (lifecycle, encryption, versioning, etc.)
57-
- `api-object-*.go`: Object operations (legal hold, retention, tagging, etc.)
58-
- `api-get-*.go`, `api-put-*.go`: GET and PUT operations
59-
- `api-list.go`: Listing operations
60-
- `api-stat.go`: Status/info operations
61-
62-
2. **Credential Management**: The `pkg/credentials/` package provides various credential providers:
63-
- Static credentials
64-
- Environment variables (AWS/MinIO)
65-
- IAM roles
66-
- STS (Security Token Service) variants
67-
- File-based credentials
68-
- Chain provider for fallback mechanisms
69-
70-
3. **Request Signing**: The `pkg/signer/` package handles AWS signature versions:
71-
- V2 signatures (legacy)
72-
- V4 signatures (standard)
73-
- Streaming signatures for large uploads
74-
75-
4. **Transport Layer**: Custom HTTP transport with:
76-
- Retry logic with configurable max retries
77-
- Health status monitoring
78-
- Tracing support via httptrace
79-
- Bucket location caching (`bucketLocCache`)
80-
- Session caching for credentials
81-
82-
5. **Helper Packages**:
83-
- `pkg/encrypt/`: Server-side encryption utilities
84-
- `pkg/notification/`: Event notification handling
85-
- `pkg/policy/`: Bucket policy management
86-
- `pkg/lifecycle/`: Object lifecycle rules
87-
- `pkg/tags/`: Object and bucket tagging
88-
- `pkg/s3utils/`: S3 utility functions
89-
- `pkg/kvcache/`: Key-value caching
90-
- `pkg/singleflight/`: Deduplication of concurrent requests
62+
1. **Modular API Organization**: API methods are split into logical files:
63+
64+
- `api-bucket-*.go`: Bucket operations (lifecycle, encryption, versioning, etc.)
65+
- `api-object-*.go`: Object operations (legal hold, retention, tagging, etc.)
66+
- `api-get-*.go`, `api-put-*.go`: GET and PUT operations
67+
- `api-list.go`: Listing operations
68+
- `api-stat.go`: Status/info operations
69+
70+
2. **Credential Management**: The `pkg/credentials/` package provides various credential providers:
71+
72+
- Static credentials
73+
- Environment variables (AWS/MinIO)
74+
- IAM roles
75+
- STS (Security Token Service) variants
76+
- File-based credentials
77+
- Chain provider for fallback mechanisms
78+
79+
3. **Request Signing**: The `pkg/signer/` package handles AWS signature versions:
80+
81+
- V2 signatures (legacy)
82+
- V4 signatures (standard)
83+
- Streaming signatures for large uploads
84+
85+
4. **Transport Layer**: Custom HTTP transport with:
86+
87+
- Retry logic with configurable max retries
88+
- Health status monitoring
89+
- Tracing support via httptrace
90+
- Bucket location caching (`bucketLocCache`\)
91+
- Session caching for credentials
92+
93+
5. **Helper Packages**:
94+
95+
- `pkg/encrypt/`: Server-side encryption utilities
96+
- `pkg/notification/`: Event notification handling
97+
- `pkg/policy/`: Bucket policy management
98+
- `pkg/lifecycle/`: Object lifecycle rules
99+
- `pkg/tags/`: Object and bucket tagging
100+
- `pkg/s3utils/`: S3 utility functions
101+
- `pkg/kvcache/`: Key-value caching
102+
- `pkg/singleflight/`: Deduplication of concurrent requests
91103

92104
### Testing Strategy
93-
- Unit tests alongside implementation files (`*_test.go`)
94-
- Comprehensive functional tests in `functional_tests.go` requiring a live MinIO server
95-
- Example programs in `examples/` directory demonstrating API usage
96-
- Build tag `//go:build mint` for integration tests
105+
106+
- Unit tests alongside implementation files (`*_test.go`\)
107+
- Comprehensive functional tests in `functional_tests.go` requiring a live MinIO server
108+
- Example programs in `examples/` directory demonstrating API usage
109+
- Build tag `//go:build mint` for integration tests
97110

98111
### Error Handling
99-
- Custom error types in `api-error-response.go`
100-
- HTTP status code mapping
101-
- Retry logic for transient failures
102-
- Detailed error context preservation
103-
104-
## Important Patterns
105-
106-
1. **Context Usage**: All API methods accept `context.Context` for cancellation and timeout control
107-
2. **Options Pattern**: Methods use Options structs for optional parameters (e.g., `PutObjectOptions`, `GetObjectOptions`)
108-
3. **Streaming Support**: Large file operations use io.Reader/Writer interfaces for memory efficiency
109-
4. **Bucket Lookup Types**: Supports both path-style and virtual-host-style S3 URLs
110-
5. **MD5/SHA256 Hashing**: Configurable hash functions for integrity checks via `md5Hasher` and `sha256Hasher`
112+
113+
- Custom error types in `api-error-response.go`
114+
- HTTP status code mapping
115+
- Retry logic for transient failures
116+
- Detailed error context preservation
117+
118+
Important Patterns
119+
------------------
120+
121+
1. **Context Usage**: All API methods accept `context.Context` for cancellation and timeout control
122+
2. **Options Pattern**: Methods use Options structs for optional parameters (e.g., `PutObjectOptions`, `GetObjectOptions`\)
123+
3. **Streaming Support**: Large file operations use io.Reader/Writer interfaces for memory efficiency
124+
4. **Bucket Lookup Types**: Supports both path-style and virtual-host-style S3 URLs
125+
5. **MD5/SHA256 Hashing**: Configurable hash functions for integrity checks via `md5Hasher` and `sha256Hasher`

‎CONTRIBUTING.md‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,23 @@
1-
### Developer Guidelines
1+
### Developer Guidelines
22

3-
``minio-go`` welcomes your contribution. To make the process as seamless as possible, we ask for the following:
3+
`minio-go` welcomes your contribution. To make the process as seamless as possible, we ask for the following:
44

5-
* Go ahead and fork the project and make your changes. We encourage pull requests to discuss code changes.
6-
- Fork it
7-
- Create your feature branch (git checkout -b my-new-feature)
8-
- Commit your changes (git commit -am 'Add some feature')
9-
- Push to the branch (git push origin my-new-feature)
10-
- Create new Pull Request
5+
- Go ahead and fork the project and make your changes. We encourage pull requests to discuss code changes.
116

12-
* When you're ready to create a pull request, be sure to:
13-
- Have test cases for the new code. If you have questions about how to do it, please ask in your pull request.
14-
- Run `go fmt`
15-
- Squash your commits into a single commit. `git rebase -i`. It's okay to force update your pull request.
16-
- Make sure `go test -race ./...` and `go build` completes.
17-
NOTE: go test runs functional tests and requires you to have a AWS S3 account. Set them as environment variables
18-
``ACCESS_KEY`` and ``SECRET_KEY``. To run shorter version of the tests please use ``go test -short -race ./...``
7+
- Fork it
8+
- Create your feature branch (git checkout -b my-new-feature)
9+
- Commit your changes (git commit -am 'Add some feature')
10+
- Push to the branch (git push origin my-new-feature)
11+
- Create new Pull Request
1912

20-
* Read [Effective Go](https://github.com/golang/go/wiki/CodeReviewComments) article from Golang project
21-
- `minio-go` project is strictly conformant with Golang style
22-
- if you happen to observe offending code, please feel free to send a pull request
13+
- When you're ready to create a pull request, be sure to:
14+
15+
- Have test cases for the new code. If you have questions about how to do it, please ask in your pull request.
16+
- Run `go fmt`
17+
- Squash your commits into a single commit. `git rebase -i`. It's okay to force update your pull request.
18+
- Make sure `go test -race ./...` and `go build` completes. NOTE: go test runs functional tests and requires you to have a AWS S3 account. Set them as environment variables`ACCESS_KEY` and `SECRET_KEY`. To run shorter version of the tests please use `go test -short -race ./...`
19+
20+
- Read [Effective Go](https://github.com/golang/go/wiki/CodeReviewComments) article from Golang project
21+
22+
- `minio-go` project is strictly conformant with Golang style
23+
- if you happen to observe offending code, please feel free to send a pull request

‎MAINTAINERS.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
# For maintainers only
1+
For maintainers only
2+
====================
23

3-
## Responsibilities
4+
Responsibilities
5+
----------------
46

57
Please go through this link [Maintainer Responsibility](https://gist.github.com/abperiasamy/f4d9b31d3186bbd26522)
68

79
### Making new releases
10+
811
Tag and sign your release commit, additionally this step requires you to have access to MinIO's trusted private key.
12+
913
```sh
1014
$ export GNUPGHOME=/media/${USER}/minio/trusted
1115
$ git tag -s 4.0.0
@@ -14,6 +18,7 @@ $ git push --tags
1418
```
1519

1620
### Update version
21+
1722
Once release has been made update `libraryVersion` constant in `api.go` to next to be released version.
1823

1924
```sh
@@ -22,14 +27,17 @@ $ grep libraryVersion api.go
2227
```
2328

2429
Commit your changes
30+
2531
```
2632
$ git commit -a -m "Update version for next release" --author "MinIO Trusted <[email protected]>"
2733
```
2834

2935
### Announce
36+
3037
Announce new release by adding release notes at https://github.com/minio/minio-go/releases from `[email protected]` account. Release notes requires two sections `highlights` and `changelog`. Highlights is a bulleted list of salient features in this release and Changelog contains list of all commits since the last release.
3138

3239
To generate `changelog`
40+
3341
```sh
3442
$ git log --no-color --pretty=format:'-%d %s (%cr) <%an>' <last_release_tag>..<latest_release_tag>
3543
```

0 commit comments

Comments
 (0)