mirror of
https://github.com/edgelesssys/constellation.git
synced 2025-05-02 06:16:08 -04:00
dev-docs: refactor and add information for newbies (#1912)
* refactor dev-docs structure and add information * improve doc * Update dev-docs/workflows/create-debug-cluster.md Co-authored-by: Daniel Weiße <66256922+daniel-weisse@users.noreply.github.com> * Update dev-docs/workflows/create-debug-cluster.md Co-authored-by: Daniel Weiße <66256922+daniel-weisse@users.noreply.github.com> * pr feedback daniel * Update dev-docs/README.md Co-authored-by: Daniel Weiße <66256922+daniel-weisse@users.noreply.github.com> * move to howto again * split up dev-setup and pull-request into sep files * fix backticks * add writing style convention + testing repo * remove OSS cluster + reduce plugins vs code * update bazel pre-pr doc * ghcr img private hint * add fetch measurement + provider sub-directory hint * add label doc + pr title check in template * add OSS build comment * Update CONTRIBUTING.md Co-authored-by: Thomas Tendyck <51411342+thomasten@users.noreply.github.com> * Update CONTRIBUTING.md Co-authored-by: Thomas Tendyck <51411342+thomasten@users.noreply.github.com> * Update dev-docs/README.md Co-authored-by: Thomas Tendyck <51411342+thomasten@users.noreply.github.com> * Update dev-docs/workflows/dev-setup.md Co-authored-by: Thomas Tendyck <51411342+thomasten@users.noreply.github.com> * thomas feedback * add go proverb mention --------- Co-authored-by: Daniel Weiße <66256922+daniel-weisse@users.noreply.github.com> Co-authored-by: Thomas Tendyck <51411342+thomasten@users.noreply.github.com>
This commit is contained in:
Adrian Stobbe
GitHub
parent
be4a636361
commit
7dcd8c3dab
15 changed files with 501 additions and 350 deletions
|
|
@ -1,39 +1,7 @@
|
|||
# Process conventions
|
||||
# Writing to customers: style policy
|
||||
|
||||
## Pull request process
|
||||
|
||||
Submissions should remain focused in scope and avoid containing unrelated commits.
|
||||
For pull requests, we employ the following workflow:
|
||||
|
||||
1. Fork the repository to your own GitHub account
|
||||
2. Create a branch locally with a descriptive name
|
||||
3. Commit changes to the branch
|
||||
4. Write your code according to our development guidelines
|
||||
5. Push changes to your fork
|
||||
6. Clean up your commit history
|
||||
7. Open a PR in our repository and summarize the changes in the description
|
||||
|
||||
## Reporting issues and bugs, asking questions
|
||||
|
||||
This project uses the GitHub issue tracker. Please check the existing issues before submitting to avoid duplicates.
|
||||
|
||||
To report a security issue, contact security@edgeless.systems.
|
||||
|
||||
Your bug report should cover the following points:
|
||||
|
||||
* A quick summary and/or background of the issue
|
||||
* Steps to reproduce (be specific, e.g., provide sample code)
|
||||
* What you expected would happen
|
||||
* What actually happens
|
||||
* Further notes:
|
||||
* Thoughts on possible causes
|
||||
* Tested workarounds or fixes
|
||||
|
||||
## Major changes and feature requests
|
||||
|
||||
You should discuss larger changes and feature requests with the maintainers. Please open an issue describing your plans.
|
||||
|
||||
[Run CI e2e tests](/.github/docs/README.md)
|
||||
Whenever you write text facing the customer (e.g, docs, warnings, errors), follow the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
|
||||
For quick reference, check [Top 10 tips for Microsoft style and voice](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice).
|
||||
|
||||
# Go code conventions
|
||||
|
||||
|
|
@ -41,6 +9,8 @@ You should discuss larger changes and feature requests with the maintainers. Ple
|
|||
|
||||
Adhere to the style and best practices described in [Effective Go](https://golang.org/doc/effective_go.html). Read [Common Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) for further information.
|
||||
|
||||
This project also aims to follow the [Go Proverbs](https://go-proverbs.github.io/).
|
||||
|
||||
## Linting
|
||||
|
||||
This projects uses [golangci-lint](https://golangci-lint.run/) for linting.
|
||||
|
|
@ -51,7 +21,7 @@ It is also recommended to use golangci-lint (and [gofumpt](https://github.com/mv
|
|||
|
||||
## Logging
|
||||
|
||||
We use a [custom subset](/internal/logger/) of [zap](https://pkg.go.dev/go.uber.org/zap) to provide logging for Constellation's services and components.
|
||||
We use a [custom subset](/internal/logger/) of [zap](https://pkg.go.dev/go.uber.org/zap) to provide logging for Constellation’s services and components.
|
||||
Usage instructions can be found in the package documentation.
|
||||
|
||||
Certain components may further specify a subset of the logger for their use. For example, the CLI has a debug-only logger, restricting the use of the logger to only `Debugf()`.
|
||||
|
|
@ -108,34 +78,6 @@ Further we try to adhere to the following guidelines:
|
|||
|
||||
As this project contains nested Go modules, we use a Go work file to ease integration with IDEs. You can find an introduction in the [Go workspace tutorial](https://go.dev/doc/tutorial/workspaces).
|
||||
|
||||
## Recommended VS Code Settings
|
||||
|
||||
The following can be added to your personal `settings.json`, but it is recommended to add it to
|
||||
the `<REPOSITORY>/.vscode/settings.json` repo, so the settings will only affect this repository.
|
||||
|
||||
```jsonc
|
||||
// Use gofumpt as formatter.
|
||||
"gopls": {
|
||||
"formatting.gofumpt": true,
|
||||
},
|
||||
// Use golangci-lint as linter. Make sure you've installed it.
|
||||
"go.lintTool":"golangci-lint",
|
||||
"go.lintFlags": ["--fast"],
|
||||
// You can easily show Go test coverage by running a package test.
|
||||
"go.coverageOptions": "showUncoveredCodeOnly",
|
||||
// Executing unit tests with race detection.
|
||||
// You can add preferences like "-v" or "-count=1"
|
||||
"go.testFlags": ["-race"],
|
||||
// Enable language features for files with build tags.
|
||||
// Attention! This leads to integration/e2e tests being executed when
|
||||
// running a package test within a package containing integration/e2e
|
||||
// tests.
|
||||
"go.buildTags": "integration e2e",
|
||||
```
|
||||
For some inexplicable reason, the `"go.lintTool":"golangci-lint",` might be overwritten. In case you don't get all linter suggestions, you might want to check the value of `go.lintTool` in the UI settings and make sure it is also set to `golangci-lint`.
|
||||
|
||||
Additionally, we use the [Redhat YAML formatter](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) to have uniform formatting in our `.yaml` files.
|
||||
|
||||
## Code documentation
|
||||
|
||||
Documentation of the latest release are available on [pkg.go.dev](https://pkg.go.dev/github.com/edgelesssys/constellation/v2).
|
||||
|
|
@ -153,46 +95,18 @@ cd "${CONSTELLATION_DIR}
|
|||
pkgsite
|
||||
```
|
||||
|
||||
You can now view the documentation on http://localhost:8080/github.com/edgelesssys/constellation/v2
|
||||
You can now view the documentation on <http://localhost:8080/github.com/edgelesssys/constellation/v2>
|
||||
</details>
|
||||
|
||||
## PR conventions
|
||||
|
||||
Our changelog is generated from PR titles. Which PR is listed in which category is determined by labels, see the [release.yml](/.github/release.yml).
|
||||
|
||||
The PR title should be structured in one of the following ways:
|
||||
|
||||
```
|
||||
<module>: <title>
|
||||
```
|
||||
|
||||
Where the `<module>` is
|
||||
|
||||
- the top level directory of the microservice or component, e.g., `joinservice`, `disk-mapper`, `upgrade-agent` but also `docs` and `rfc`
|
||||
- in internal, the second level directory
|
||||
- `deps` for dependency upgrades
|
||||
- `ci` for things that are CI related
|
||||
|
||||
and `<title>` is all lower case (except proper names, including acronyms).
|
||||
Ticket numbers shouldn't be part of the title.
|
||||
|
||||
In case the scope of your PR is too wide, use the alternative format.
|
||||
|
||||
```
|
||||
<Title>
|
||||
```
|
||||
|
||||
and `<Title>` starts with a capital letter.
|
||||
|
||||
## CLI reference
|
||||
|
||||
The command reference within the CLI should follow the following conventions:
|
||||
|
||||
- Short description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends without a period. It should be a single sentence.
|
||||
- Long description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends with a period.
|
||||
- If the long description contains multiple sentences, the first sentence is formatted as a long description, followed by 2 newlines and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period.
|
||||
- Flag: Starts with a lowercase letter, beginnings of sentences, names and acronyms are capitalized, ends without a period.
|
||||
- If a flag contains multiple sentences, the first sentence is formatted as a normal flag, followed by a newline and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period.
|
||||
* Short description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends without a period. It should be a single sentence.
|
||||
* Long description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends with a period.
|
||||
* If the long description contains multiple sentences, the first sentence is formatted as a long description, followed by 2 newlines and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period.
|
||||
* Flag: Starts with a lowercase letter, beginnings of sentences, names and acronyms are capitalized, ends without a period.
|
||||
* If a flag contains multiple sentences, the first sentence is formatted as a normal flag, followed by a newline and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period.
|
||||
|
||||
## Naming convention
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue