Skip to content
This repository has been archived by the owner on Apr 2, 2024. It is now read-only.

Commit

Permalink
Merge pull request #17 from jakubmkowalski/docs/updates-readme-and-co…
Browse files Browse the repository at this point in the history 
…de_standards

docs(BUX-442): updates readme and code standards
  • Loading branch information
@wregulski
wregulski authored Jan 19, 2024
2 parents cfeb83b + 2e8fad9 commit 2b3ebcf
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 82 deletions.
88 changes: 52 additions & 36 deletions .github/CODE_STANDARDS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,45 @@

- [Code Standards \& Contributing Guidelines](#code-standards--contributing-guidelines)
- [Most important rules - Quick Checklist](#most-important-rules---quick-checklist)
- [1. Code style and formatting - official guidelines](#1-code-style-and-formatting---official-guidelines)
- [1 Code style and formatting - official guidelines](#1-code-style-and-formatting---official-guidelines)
- [1.1 In GO applications or libraries, we follow the official guidelines](#11-in-go-applications-or-libraries-we-follow-the-official-guidelines)
- [Additional useful resources with GO recommendations, best practices and the common mistakes](#additional-useful-resources-with-go-recommendations-best-practices-and-the-common-mistakes)
- [2. Code Rules](#2-code-rules)
- [2.1. Self-documenting code](#21-self-documenting-code)
- [2 Code Rules](#2-code-rules)
- [2.1 Self-documenting code](#21-self-documenting-code)
- [As a Developer](#as-a-developer)
- [As a PR Reviewer](#as-a-pr-reviewer)
- [2.2. Tests](#22-tests)
- [2.2 Tests](#22-tests)
- [Principle](#principle)
- [Guidelines for Writing Tests](#guidelines-for-writing-tests)
- [Pull request title with a scope and task number](#pull-request-title-with-a-scope-and-task-number)
- [2.3 Code Review](#23-Code-Review)
- [Code Review Checklist](#code-review-checklist)
- [3 Contributing](#3-contributing)
- [3.1 Pull Requests && Issues](#31-pull-requests--issues)
- [3.2 Conventional Commits & Pull Requests Naming](#32-conventional-commits--pull-requests-naming)
- [Overview](#overview)
- [Structure](#structure)
- [Types](#types)
- [Conventional Commits - Automatic Versioning](#conventional-commits---automatic-versioning)
- [Scope](#scope)
- [Further Reading](#further-reading)
- [Examples](#examples)
- [Pull request title with a scope and task number](#pull-request-title-with-a-scope-and-task-number)
- [3.3 Branching](#33-branching)
- [Choosing branch names](#choosing-branch-names)
- [Descriptiveness](#descriptiveness)
- [Include Issue Number](#include-issue-number)
- [Deleting Branches After Merging](#deleting-branches-after-merging)
- [Remove Remote Branches](#remove-remote-branches)
- [Recommendation: Clean Local Branches](#recommendation-clean-local-branches)
- [4. Documentation Code Standards](#4-documentation-code-standards)
- [4 Documentation Code Standards](#4-documentation-code-standards)
- [4.1 Overview](#41-overview)
- [4.2 Principles](#42-principles)
- [4.3 Feature Documentation](#43-feature-documentation)
- [4.3.1 Necessity](#431-necessity)
- [4.3.2 Examples](#432-examples)
- [Necessity](#necessity)
- [Examples](#examples)
- [4.4 External Features](#44-external-features)
- [4.5 Markdown usage](#45-markdown-usage)
- [4.5 Conclusion](#45-conclusion)
- [4.6 Conclusion](#46-conclusion)

## Most important rules - Quick Checklist

Expand All @@ -41,12 +53,12 @@
- [ ] Keep documentation clear, concise, up-to-date, and accessible.
- [ ] Branching - choose consistent naming conventions, include issue number, delete branches after merging.

## 1. Code style and formatting - official guidelines
## 1 Code style and formatting - official guidelines

### 1.1 In GO applications or libraries, we follow the official guidelines

- [Effective Go](https://go.dev/doc/effective_go) - official Go guidelines
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) - official Go code review comments
- [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) - official Go code review comments
- [Go Examples](https://pkg.go.dev/testing#hdr-Examples) - official Go examples - used in libraries to explain how to use their exposed features
- [Go Test](https://pkg.go.dev/testing) - official Go testing package & recommendations
- [Go Linter](https://golangci-lint.run/) - golangci-lint - only codestyle checks
Expand All @@ -57,9 +69,9 @@

- [Go Styles by Google](https://google.github.io/styleguide/go/) - Google's Go Style Guide
- [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md) - Uber's Go Style Guide
- [Go Common Mistakes](https://github.com/golang/go/wiki/CommonMistakes) - Common Mistakes in Go
- [Go Common Mistakes](https://go.dev/wiki/CommonMistakes) - Common Mistakes in Go

## 2. Code Rules
## 2 Code Rules

### 2.1. Self-documenting code

Expand All @@ -75,7 +87,7 @@
- Be vigilant of newly added comments during reviews. If a comment appears unnecessary, uninformative, or could be replaced with a function, do not hesitate to highlight this.
- Assess the meaningfulness and clarity of function names, ensuring they contribute to self-documenting code.

### 2.2. Tests
### 2.2 Tests

#### Principle

Expand Down Expand Up @@ -140,7 +152,7 @@ Of course not only error paths should be covered - **we should highlight the hap

10. **Responsiveness**: Both authors and reviewers should be timely in their responses. Authors should address all review comments, and reviewers should re-review changes promptly.

#### 2.3.3 Code Review Checklist
#### Code Review Checklist

- [ ] Does the code adhere to the project’s coding standards?
- [ ] Are there sufficient tests, and do they cover a variety of cases?
Expand All @@ -155,29 +167,30 @@ Of course not only error paths should be covered - **we should highlight the hap
This checklist serves as a guide to both authors and reviewers to ensure a thorough and effective code review process.
## 3. Contributing
## 3 Contributing
### 3.1 Pull Requests && Issues
We have separate templates for Pull Requests and Issues. Please use them when creating a new PR or Issue.
### 3.2 Conventional Commits & Pull Requests Naming
#### 3.2.1 Overview
#### Overview
In an effort to maintain clarity and coherence in our commit history, we are adopting the Conventional Commits style for all commit messages across our repositories. This uniform format not only enhances the readability of our commit history but also facilitates automated tools in generating changelogs and extracting valuable information effectively.
#### 3.2.2 Structure
#### Structure
Conventional Commits follow a structured format: `type(scope): description`, where:
- `type`: Represents the nature of the commit (e.g., feat, fix, chore).
- `scope`: Denotes the relevant module or issue.
- `description`: Provides a brief explanation of the change.
When introducing breaking changes, an `!` should be appended after the `type/scope`: `feat(#123)!: introduce a breaking change`.
When introducing breaking changes, an `!` should be appended after the `type/scope`:<br/>
`feat(#123)!: introduce a breaking change`.
#### 3.2.3 Types
#### Types
- `feat`: Utilized when introducing a new feature to the codebase.
- `fix`: Employed when resolving a bug or issue in the code.
Expand All @@ -191,20 +204,20 @@ When introducing breaking changes, an `!` should be appended after the `type/sco
- `ci`: Applied to changes concerning the Continuous Integration (CI) configuration or scripts.
- `deps`: Used when updating or modifying dependencies.

#### 3.2.4 Conventional Commits - Automatic Versioning
#### Conventional Commits - Automatic Versioning

In our repositories, we use Conventional Commits to automatically generate the version number for our releases.

It works like this:

`fix: which represents bug fixes, and correlates to a SemVer patch.`
`feat: which represents a new feature, and correlates to a SemVer minor.`
`fix: which represents bug fixes, and correlates to a SemVer patch.`<br/>
`feat: which represents a new feature, and correlates to a SemVer minor.`<br/>
`feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.`

Real life example:

`feat(#123)!: introduce breaking change - 1.0.0 -> 2.0.0`
`feat(#124): introduce new feature - 2.0.0 -> 2.1.0`
`feat(#123)!: introduce breaking change - 1.0.0 -> 2.0.0`<br/>
`feat(#124): introduce new feature - 2.0.0 -> 2.1.0`<br/>
`fix(#125): fix a bug - 2.1.0 -> 2.1.1`

Given a version number MAJOR.MINOR.PATCH, increment the:
Expand All @@ -216,17 +229,17 @@ Additional labels for pre-release and build metadata are available as extensions

More about Semantic Versioning can be found [here](https://semver.org/).

#### 3.2.5 Scope
#### Scope

We have standardized the use of JIRA/GitHub issue numbers as the `scope` in commits within our team. This practice aids in easily tracing the origin of changes.

In the absence of an existing issue for your changes, please create one in the client’s JIRA system. If the change is not client-related, establish a GitHub issue in the repository.

#### 3.2.6 Further Reading
#### Further Reading

Additional information and guidelines on Conventional Commits can be found [here](https://www.conventionalcommits.org/en/v1.0.0/).

#### 3.2.7 Examples
#### Examples

##### Commit message with scope

Expand Down Expand Up @@ -260,11 +273,13 @@ debugo feature - checkpoint full work
#### Descriptiveness

- Branch names should be descriptive and represent the task/feature at hand.
- Use hyphens to separate words for readability, e.g., `feature/add-login-button`.
- Use hyphens to separate words for readability, e.g.,<br/>
`feature/add-login-button`.

#### Include Issue Number

- If applicable, include the issue number in the branch name for easy tracking, e.g., `feature/123-add-login-button`.
- If applicable, include the issue number in the branch name for easy tracking, e.g.,<br/>
`feature/123-add-login-button`.

#### Deleting Branches After Merging

Expand All @@ -275,9 +290,10 @@ debugo feature - checkpoint full work

#### Recommendation: Clean Local Branches

- Regularly prune local branches that have been deleted remotely with `git fetch -p && git branch -vv | grep 'origin/.*: gone]' | awk '{print $1}' | xargs git branch -d`.
- Regularly prune local branches that have been deleted remotely with <br/>
`git fetch -p && git branch -vv | grep 'origin/.*: gone]' | awk '{print $1}' | xargs git branch -d`.

## 4. Documentation Code Standards
## 4 Documentation Code Standards

### 4.1 Overview

Expand All @@ -291,11 +307,11 @@ A well-documented codebase is pivotal for both internal development and external

### 4.3 Feature Documentation

#### 4.3.1 Necessity
#### Necessity

Every feature developed should be accompanied by adequate documentation. The necessity for documentation becomes even more pronounced for open-source projects, where clear instructions and examples facilitate easier adoption and contribution from the community.

#### 4.3.2 Examples
#### Examples

- **Inclusion of Examples**: Where applicable, documentation should include practical examples demonstrating the feature’s usage and benefits. Examples act as a practical guide, aiding developers in understanding and implementing the feature correctly.
- **Clarity of Examples**: Examples should be clear, concise, and relevant, illustrating the functionality of the feature effectively.
Expand All @@ -311,8 +327,8 @@ For projects exposing external features:

We should write documentation in Markdown format. It allows us to write documentation in a simple and readable way. It's also easy to convert Markdown to HTML or PDF or create a website from it.
[Markdown Guide](markdownguide.org) - Comprehensive guide to Markdown syntax.
[Markdown Guide](https://markdownguide.org) - Comprehensive guide to Markdown syntax.
### 4.5 Conclusion
### 4.6 Conclusion
Adhering to documentation code standards is integral for maintaining a healthy, understandable, and contributable codebase. By ensuring every feature is well-documented, with the inclusion of clear examples where necessary, we foster a conducive environment for development and community engagement, particularly in open-source projects.
65 changes: 19 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,36 @@
<div align="center">

# BUX: Models
> Get started using [BUX](https://getbux.io) in five minutes

[![Release](https://img.shields.io/github/release-pre/BuxOrg/bux-models.svg?logo=github&style=flat&v=1)](https://github.com/BuxOrg/bux-models/releases)
[![Build Status](https://img.shields.io/github/actions/workflow/status/BuxOrg/bux-models/run-tests.yml?branch=master&logo=github&v=1)](https://github.com/BuxOrg/bux-models/actions)
[![Report](https://goreportcard.com/badge/github.com/BuxOrg/bux-models?style=flat&v=1)](https://goreportcard.com/report/github.com/BuxOrg/bux-models)
[![Mergify Status](https://img.shields.io/endpoint.svg?url=https://api.mergify.com/v1/badges/BuxOrg/bux-models&style=flat&v=1)](https://mergify.io)
[![Go](https://img.shields.io/github/go-mod/go-version/BuxOrg/bux-models?v=1)](https://golang.org/)
<br>

[![Go](https://img.shields.io/github/go-mod/go-version/BuxOrg/bux-models?v=1)](https://golang.org/)
[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat&v=1)](https://github.com/RichardLitt/standard-readme)
[![Makefile Included](https://img.shields.io/badge/Makefile-Supported%20-brightgreen?=flat&logo=probot&v=1)](Makefile)
[![Sponsor](https://img.shields.io/badge/sponsor-BuxOrg-181717.svg?logo=github&style=flat&v=2)](https://github.com/sponsors/BuxOrg)
[![Donate](https://img.shields.io/badge/donate-bitcoin-ff9900.svg?logo=bitcoin&style=flat&v=2)](https://gobitcoinsv.com/#sponsor?utm_source=github&utm_medium=sponsor-link&utm_campaign=bux-models&utm_term=bux-models&utm_content=bux-models)

<br/>
</div>

> Get started using [BUX](https://getbux.io) in five minutes
## Table of Contents
- [What is BUX?](#what-is-bux)
- [About](#about)
- [Installation](#installation)
- [Documentation](#documentation)
- [Examples & Tests](#examples--tests)
- [Benchmarks](#benchmarks)
- [Code Standards](#code-standards)
- [Usage](#usage)
- [Examples & Tests](#examples--tests)
- [Benchmarks](#benchmarks)
- [Code Standards](#code-standards)
- [Contributing](#contributing)
- [License](#license)

<br/>

## What is BUX?
## About
[Read more about BUX](https://getbux.io)

<br/>
Expand Down Expand Up @@ -164,7 +167,9 @@ vet Run the Go vet application

<br/>

## Examples & Tests
## Usage

### Examples & Tests
All unit tests run via [GitHub Actions](https://github.com/BuxOrg/bux-models/actions) and
uses [Go version 1.18.x](https://golang.org/doc/go1.18). View the [configuration file](.github/workflows/run-tests.yml).

Expand All @@ -184,7 +189,7 @@ make test-short

<br/>

## Benchmarks
### Benchmarks
Run the Go benchmarks:
```shell script
make bench
Expand All @@ -197,44 +202,12 @@ Read more about this Go project's [code standards](.github/CODE_STANDARDS.md).

<br/>

## Usage
Checkout all the tests!

<br/>

## Contributing
View the [contributing guidelines](.github/CONTRIBUTING.md) and follow the [code of conduct](.github/CODE_OF_CONDUCT.md).

All kinds of contributions are welcome!
<br/>

### How can I help?
All kinds of contributions are welcome :raised_hands:!
The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:.
You can also support this project by [becoming a sponsor on GitHub](https://github.com/sponsors/mrz1836) :clap:
or by making a [**bitcoin donation**](https://gobitcoinsv.com/#sponsor?utm_source=github&utm_medium=sponsor-link&utm_campaign=bux-models&utm_term=bux-models&utm_content=bux-models) to ensure this journey continues indefinitely! :rocket:

[![Stars](https://img.shields.io/github/stars/BuxOrg/bux-models?label=Please%20like%20us&style=social&v=1)](https://github.com/BuxOrg/bux-models/stargazers)

To get started, take a look at [code standards](.github/CODE_STANDARDS.md).
<br/>

### Contributors ✨
Thank you to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tr>
<td align="center"><a href="https://mrz1818.com"><img src="https://avatars.githubusercontent.com/u/3743002?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Mr. Z</b></sub></a><br /><a href="#infra-mrz1836" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/BuxOrg/bux-models/commits?author=mrz1836" title="Code">💻</a> <a href="#maintenance-mrz1836" title="Maintenance">🚧</a> <a href="#security-mrz1836" title="Security">🛡️</a></td>
</tr>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

> This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
View the [contributing guidelines](.github/CODE_STANDARDS.md#3-contributing) and follow the [code of conduct](.github/CODE_OF_CONDUCT.md).

<br/>

Expand Down

0 comments on commit 2b3ebcf

Please sign in to comment.