Skip to content

Commit 991cb3a

Browse files
adecaroadecaro
authored
development documentation (#1163)
Signed-off-by: Angelo De Caro <adc@zurich.ibm.com>
1 parent 3cae3f6 commit 991cb3a

File tree

12 files changed

+644
-17
lines changed

12 files changed

+644
-17
lines changed

‎Makefile‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ install-tools:
2020
# Thanks for great inspiration https://marcofranssen.nl/manage-go-tools-via-go-modules
2121
@echo Installing tools from tools/tools.go
2222
@cd tools; cat tools.go | grep _ | awk -F'"' '{print $$2}' | xargs -tI % go install %
23+
@$(MAKE) install-linter-tool
2324

2425
.PHONY: download-fabric
2526
download-fabric:
@@ -137,4 +138,14 @@ txgen:
137138

138139
.PHONY: clean-all-containers
139140
clean-all-containers:
140-
@if [ -n "$$(docker ps -aq)" ]; then docker rm -f $$(docker ps -aq); else echo "No containers to remove"; fi
141+
@if [ -n "$$(docker ps -aq)" ]; then docker rm -f $$(docker ps -aq); else echo "No containers to remove"; fi
142+
143+
.PHONY: lint
144+
lint:
145+
@echo "Running Go Linters..."
146+
golangci-lint run --color=always --timeout=4m
147+
148+
.PHONY: install-linter-tool
149+
install-linter-tool:
150+
@echo "Installing golangci Linter"
151+
@curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(HOME)/go/bin v2.1.6

‎README.md‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -61,12 +61,6 @@ FABRIC_VERSION=2.5 make download-fabric
6161
```
6262

6363
If you want to provide your own versions of the fabric binaries then just set `FAB_BINS` to the directory where all the fabric binaries are stored.
64-
65-
# Utilities
66-
67-
- [`tokengen`](./cmd/tokengen/README.md) is an utility for generating Fabric Token-SDK material.
68-
It is provided as a means of preconfiguring public parameters, token chaincode, and so.
69-
It would normally not be used in the operation of a production network.
7064

7165
# Additional Resources
7266

@@ -107,17 +101,9 @@ The Fabric Token SDK has evolved beyond its initial focus on Hyperledger Fabric.
107101

108102
With a robust Fabric Token SDK, developing secure and efficient enterprise-grade tokenized applications becomes a reality, offering flexibility for developers to choose the platform that best suits their needs.
109103

110-
# Testing Philosophy
111-
112-
[Write tests. Not too many. Mostly Integration](https://kentcdodds.com/blog/write-tests)
113-
114-
We also believe that when developing new functions running tests is preferable than running the application to verify the code is working as expected.
115-
116-
For more information about our integration tests, look [`here`](./docs/itests.md).
117-
118-
# Versioning
104+
# Development
119105

120-
We use [`SemVer`](https://semver.org/) for versioning. For the versions available, see the [`tags on this repository`](https://github.com/hyperledger-labs/fabric-token-sdk/tags).
106+
For additional information about the development of the Token SDK, visit this [`section`](./docs/development/development.md).
121107

122108
# License
123109

‎docs/development/development.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Development Guidelines
2+
3+
This page contains link to the development guidelines and more.
4+
5+
- [General Guidelines](./general.md)
6+
- [Writing idiomatic, effective, and clean Go code](./idiomatic.md)
7+
- [Best Practices for Versioning Go Projects](./versioning.md)
8+
- [Development Tools](./tools.md)
9+
- [Linting](./linting.md)
10+
- [Monitoring](./monitoring.md)
11+
- [Mock Files Generation](./mock.md)
12+
- [Tools: tokengen](./tokengen.md)
13+
14+
## Useful resources
15+
16+
- [How to use SDK's](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/platform/sdk.md): Current structure and guidelines for development of the SDK's-
17+
- [Common problems](https://github.com/hyperledger-labs/fabric-token-sdk/wiki/Common-problems): Common problems you may encounter. You can document more issues to help onboarding of future developers.

‎docs/development/general.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Development Guidelines
2+
3+
This document outlines the contribution and development practices to ensure a clean and maintainable Git history.
4+
5+
## Creating a Branch
6+
7+
When checking out a new branch from `main` to work on an issue, give it a name associated with the issue it is addressing
8+
For example branch name: `123-user-management`.
9+
10+
Work on your local branch and make as many local commits as needed.
11+
12+
## Commit Sign-Off Requirement
13+
14+
All commits must be **signed off** to certify that the contributor agrees to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/).
15+
This is a legal statement indicating that you wrote the code or have the right to contribute it.
16+
17+
### How to Sign Off a Commit
18+
19+
When creating a commit, use the `-s` flag:
20+
21+
```bash
22+
git commit -s -m "feat: add token validation logic"
23+
```
24+
25+
This will append a `Signed-off-by` line with your name and email address, matching the information in your Git configuration.
26+
27+
Example:
28+
29+
```
30+
Signed-off-by: Jane Doe <jane.doe@example.com>
31+
```
32+
33+
If you forgot to sign off a commit, you can amend the last commit:
34+
35+
```bash
36+
git commit --amend -s
37+
```
38+
39+
Or for multiple commits, you can rebase and add the sign-offs:
40+
41+
```bash
42+
git rebase -i HEAD~N # replace N with number of commits to edit
43+
# Then mark each commit with 'edit' and sign off each one:
44+
git commit --amend -s
45+
git rebase --continue
46+
```
47+
48+
## Ensure Linear Commit History
49+
50+
We follow a linear commit history to keep the Git log clean and easy to follow.
51+
We should have one compound commit per feature/issue to make it easy to track the project history.
52+
This involves the following steps:
53+
- Iteratively develop in your branch adding as many intermediate commits as needed.
54+
- Before merging, rebase your branch to the latest main to avoid merge conflicts.
55+
- Make a pull request and iterate on comments.
56+
- Once approved, squash and merge your PR.
57+
### Rebase Workflow
58+
59+
1. Before pushing your branch, always rebase on the latest `main`:
60+
61+
```bash
62+
git fetch origin
63+
git rebase origin/main
64+
```
65+
66+
2. If there are any conflicts, resolve them and continue the rebase:
67+
68+
```bash
69+
git status # See conflicted files
70+
# Edit and resolve conflicts
71+
git add <resolved-files>
72+
git rebase --continue
73+
```
74+
75+
3. Force push your rebased branch to update your pull request:
76+
77+
```bash
78+
git push --force-with-lease
79+
```
80+
81+
### Why No Merge Commits?
82+
83+
- They clutter the history.
84+
- They make it harder to identify what changes were made.
85+
- They complicate tools that generate changelogs or audit logs.
86+
87+
88+
### Pull Request Requirements
89+
90+
When ready to make a `Pull request`, do the following:
91+
- Open the PR in Github
92+
- Create a title reflecting the task and `issue` number
93+
- Example Title: `Add user management (#123)`
94+
- The #123 will become a clickable link to the `issue`, and will also show up in the commit history
95+
- Create additional text as needed
96+
- Example Text:
97+
```
98+
Author: Jens Jelitto
99+
Reviewers: Bar, Angelo
100+
Issue: /link (if issue is attached)
101+
Description: any additional content description
102+
```
103+
104+
### Finalize Pull Request
105+
106+
Once the review process is finished, finalize the PR:
107+
- Do a `squash and merge` (NOT `Merge commit`!)
108+
- Delete the branch
109+
- Close the PR
110+
111+
To maintain clarity and traceability across contributions, all pull requests must adhere to the following:
112+
113+
- **Description**: Every pull request must include a meaningful description outlining the purpose and scope of the change.
114+
- **Labels**: Assign appropriate labels to help with categorization and prioritization.
115+
- **Project Assignment**: The pull request must be added to the **Fabric Token SDK** project with an appropriate status (e.g., “To Do”, “In Progress”, “In Review”, etc.).
116+
The maintainers are responsible to set this appropriately. If the creator of the PR is a maintainer, then they will also set this.
117+
- **Associated Issue**: A GitHub Issue must be linked to the pull request.
118+
This should be done via the Development section of the GitHub PR interface (not just mentioned in the description).
119+
This ensures the PR is formally connected to the issue for proper project tracking and status updates.
120+
- **One Approve Policy**: Each PR must receive at least one `approve` from the maintainers of the project before it can be merged.
121+
122+
This ensures that all contributions are tracked, visible on the project board, and aligned with the roadmap.
123+
124+
## Epic and Issue Creation Guidelines
125+
126+
For larger features or workstreams, create a **GitHub Epic** to group related issues and provide overarching context. Each epic should include:
127+
128+
- **A clear description** outlining the goal or deliverable of the epic.
129+
- **A checklist** referencing all related GitHub Issues that the epic encompasses. This provides a roadmap for tracking progress and dependencies.
130+
131+
Don't forget to populate the metadata (like Project, Milestone, and so on) for both epics, issues, and PRs.
132+
133+
Example Epic Template:
134+
135+
```markdown
136+
## Objective
137+
This epic tracks the implementation of <feature/initiative name>, including all tasks required for completion.
138+
139+
## Task List
140+
- #101
141+
- #102
142+
- #103
143+
```
144+
Github will replace `#101` with the title of corresponding Github Issue and report the status as well.
145+
146+
147+
Organizing work in epics ensures better visibility for contributors and maintainers, and helps align development with roadmap goals.
148+
149+
## Additional Notes
150+
151+
- Use clear, concise commit messages (preferably using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)).
152+
- Squash commits as needed before submission to keep the history clean.
153+
- Open a pull request only after your branch is up-to-date and rebased on `main`.

‎docs/development/idiomatic.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Writing idiomatic, effective, and clean Go code
2+
3+
Writing idiomatic, effective, and clean Go code involves adhering to a set of principles and practices that leverage the language's unique design.
4+
Here are some key guidelines, often considered "commandments" in the Go community:
5+
6+
**The Ten Commandments of Idiomatic Go:**
7+
8+
1. **Thou Shalt Format Thy Code with `golangci-lint`:**
9+
10+
* **Guideline:** Use the `golangci-lint` tool religiously. It enforces a standard, opinionated style for indentation, spacing, and alignment.
11+
We support the tool directly in our `Makefile`. You can run:
12+
```bash
13+
make lint
14+
```
15+
and
16+
```bash
17+
make checks
18+
```
19+
* This consistency makes Go code highly readable and reduces time spent on style debates. Many editors and IDEs integrate `gofmt` automatically on save. The `goimports` tool is a superset of `gofmt` that also manages imports.
20+
* **References:**
21+
* [Effective Go - Formatting](https://www.google.com/search?q=https://go.dev/doc/effective_go%23formatting)
22+
* [Go standards and style guidelines - GitLab Docs](https://docs.gitlab.com/development/go_guide/) (Mentions `goimports`)
23+
* [golangci-lint Fast linters runner for Go](https://github.com/golangci/golangci-lint)
24+
25+
2. **Thou Shalt Handle Errors Explicitly:**
26+
27+
* **Guideline:** Go treats errors as values. Functions that can fail should return an error as the last return value.
28+
Always check error returns and handle them gracefully. Avoid ignoring errors using the blank identifier `_`.
29+
Propagate errors back up the call stack or handle them appropriately (e.g., logging, retrying).
30+
Use `errors.Is` and `errors.As` for checking error types or values, especially in Go 1.13+. Error strings should be lowercase and not end with punctuation.
31+
* **References:**
32+
* [Effective Go - Errors](https://www.google.com/search?q=https://go.dev/doc/effective_go%23errors)
33+
* [Golang 10 Best Practices - Proper Error Handling](https://codefinity.com/blog/Golang-10-Best-Practices)
34+
* [Go standards and style guidelines - GitLab Docs](https://docs.gitlab.com/development/go_guide/) (Mentions `errors.Is` and `errors.As`)
35+
36+
3. **Thou Shalt Favor Composition Over Inheritance:**
37+
38+
* **Guideline:** Go does not have traditional class inheritance.
39+
Achieve code reuse and flexibility through composition (embedding structs) and interfaces.
40+
Design small, focused interfaces that define behavior.
41+
* **References:**
42+
* [Idiomatic Design Patterns in Go - Composition](https://ayada.dev/go-roadmap/idiomatic-design-patterns-in-go/)
43+
44+
4. **Thou Shalt Design Small, Focused Interfaces:**
45+
46+
* **Guideline:** Go's interfaces are implicitly implemented.
47+
Define interfaces on the consumer side, specifying only the methods a client needs.
48+
This promotes decoupling and testability.
49+
Name interfaces with an "-er" suffix (e.g., `Reader`, `Writer`) when they define a single method, though this is a convention, not a strict rule for all interfaces.
50+
* **References:**
51+
* [Effective Go - Interfaces](https://www.google.com/search?q=https://go.dev/doc/effective_go%23interfaces)
52+
* [Golang style guide - Mattermost Developers](https://www.google.com/search?q=https://developers.mattermattermost.com/contribute/more-info/server/style-guide/%23interfaces) (Mentions the "-er" convention)
53+
54+
5. **Thou Shalt Write Concurrent Code Using Goroutines and Channels:**
55+
56+
* **Guideline:** Embrace Go's built-in concurrency primitives.
57+
Use goroutines for concurrent execution and channels for safe communication and synchronization between them.
58+
Understand the Go memory model and use tools like the race detector to avoid race conditions.
59+
* **References:**
60+
* [Effective Go - Concurrency](https://www.google.com/search?q=https://go.dev/doc/effective_go%23concurrency)
61+
* [Golang 10 Best Practices - Efficient Use of Goroutines](https://codefinity.com/blog/Golang-10-Best-Practices)
62+
* [Idiomatic Design Patterns in Go - Concurrency with Goroutines and Channels](https://ayada.dev/go-roadmap/idiomatic-design-patterns-in-go/)
63+
64+
6. **Thou Shalt Not Use Global Variables Extensively:**
65+
66+
* **Guideline:** Limit the use of global variables to avoid side effects and improve testability and maintainability.
67+
Pass data explicitly through function parameters and return values, or use struct fields.
68+
* **References:**
69+
* [Golang 10 Best Practices - Minimize Global Variables](https://codefinity.com/blog/Golang-10-Best-Practices)
70+
* [Go standards and style guidelines - GitLab Docs](https://docs.gitlab.com/development/go_guide/) (Avoid global variables)
71+
72+
7. **Thou Shalt Keep Functions Small and Single-Purpose:**
73+
74+
* **Guideline:** Design functions that do one thing well.
75+
Short, focused functions are easier to understand, test, and maintain.
76+
Avoid excessive nesting and complex logic within a single function.
77+
* **References:**
78+
* [Golang 10 Best Practices - Keep Functions Focused](https://codefinity.com/blog/Golang-10-Best-Practices)
79+
* [Golang Clean Code Guide – 2 - Simplicity in Action: Short and Focused Functions](https://withcodeexample.com/golang-clean-code-guide-2/)
80+
81+
8. **Thou Shalt Write Tests:**
82+
83+
* **Guideline:** Go has a built-in testing framework.
84+
Write unit tests for your code to ensure correctness and provide examples of how to use your functions and types.
85+
Table-driven tests are a common and effective pattern in Go.
86+
* **References:**
87+
* [Effective Go - Testing](https://www.google.com/search?q=https://go.dev/doc/effective_go%23testing)
88+
* [Go standards and style guidelines - GitLab Docs](https://docs.gitlab.com/development/go_guide/) (Defining test cases)
89+
90+
9. **Thou Shalt Document Exported Symbols:**
91+
92+
* **Guideline:** Provide clear and concise documentation for all exported functions, types, variables, and constants.
93+
Comments should explain *what* the code does and *why*, especially for non-obvious parts.
94+
Use Godoc conventions for easily generated documentation.
95+
* **References:**
96+
* [Go Doc Comments - The Go Programming Language](https://go.dev/doc/comment)
97+
* [Documentation and Comments in Go - With Code Example](https://withcodeexample.com/golang-documentation-and-comments-guide)
98+
99+
10. **Thou Shalt Be Mindful of Performance and Allocations:**
100+
101+
* **Guideline:** While Go is performant, be aware of potential bottlenecks.
102+
Understand how slices, maps, and pointers work to minimize unnecessary allocations and garbage collection pressure, especially in performance-critical code.
103+
Use tools like the pprof profiler to identify performance issues.
104+
105+
**Additional Recommended Reading and Style Guides:**
106+
107+
* [Effective Go](https://go.dev/doc/effective_go) - A fundamental guide from the Go team on writing clear, idiomatic Go code.
108+
* [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) - A wiki page listing common style issues and suggestions.
109+
* [Google Go Style Guide](https://google.github.io/styleguide/go/) - Google's internal style guide for Go.
110+
* [Uber Go Style Guide](https://github.com/uber-go/guide) - Uber's widely referenced style guide for Go.
111+
112+
These resources provide more detailed explanations and examples for each of the guidelines mentioned above, helping you to write more effective and idiomatic Go code.

‎docs/development/linting.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Linting
2+
3+
golangci-lint is a highly efficient and widely used command-line tool for linting Go source code.
4+
It acts as a runner for multiple independent linters, executing them in parallel to speed up the analysis process.
5+
By aggregating the results from various linters, golangci-lint helps identify a broad range of potential issues,
6+
including code style violations, programming errors, complexity problems, and potential security vulnerabilities,
7+
contributing to cleaner and more maintainable Go projects.
8+
9+
To install the linter, follow the instruction here: [`https://golangci-lint.run/welcome/install/#local-installation`](https://golangci-lint.run/welcome/install/#local-installation).
10+
11+
To run the linter for the project, just run
12+
13+
```bash
14+
make lint
15+
```
16+
17+
To change the configuration of the linter, check the `.golangci.yml` (To be included soon).
18+
This configuration is also used by our CI.

‎docs/development/mock.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Generation Mock Files
2+
3+
We use `counterfeiter` to generate mocks.
4+
5+
For example, `token/driver/mock` contains mock auto-generated files for the Driver API..
6+
The generation directives can be found close to the interface that needs to be mocked, for example at `token/driver/transfer.go`:
7+
```
8+
//go:generate counterfeiter -o mock/ts.go -fake-name TransferService . TransferService
9+
```
10+
To regenerate all mock files, go to `token/driver` and run `go generate`.
11+
The same applies to other packages containing the `//go:generate` directive.

‎docs/development/monitoring.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Monitoring
2+
3+
We adopt the monitoring infrastructure provided by the [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/platform/view/monitoring.md).
4+
5+
We use the following two methods to monitor the performance of the application:
6+
* **Metrics** provide an overview of the overall system performance using aggregated results, e.g. total requests, requests per second, current state of a variable, average duration, percentile of duration
7+
* **Traces** help us analyze single requests by breaking down their lifecycles into smaller components

0 commit comments

Comments
 (0)