docs: Move contribution guide to docs website
Also adding a CONTRIBUTING.md file for GitHub links and easier discovery for someone browsing the repository’s files. Signed-off-by: Helder Correia <174525+helderco@users.noreply.github.com>
This commit is contained in:
parent
991c8dc6ff
commit
ac23b26426
14
CONTRIBUTING.md
Normal file
14
CONTRIBUTING.md
Normal file
@ -0,0 +1,14 @@
|
|||||||
|
# Contributing to Dagger
|
||||||
|
|
||||||
|
As an open source project, Dagger welcomes all contributions.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- Opening issues for bug reports, feature requests or general feedback
|
||||||
|
- Creating pull requests for code or documentation improvements
|
||||||
|
- Reviewing and discussing open issues and pull requests
|
||||||
|
- Helping other users
|
||||||
|
|
||||||
|
Extensive contribution guidelines are available in the repository at `docs/guides/1227-contributing.md`, or online at:
|
||||||
|
|
||||||
|
[https://docs.dagger.io/1227/contributing](https://docs.dagger.io/1227/contributing)
|
174
docs/guides/1227-contributing.md
Normal file
174
docs/guides/1227-contributing.md
Normal file
@ -0,0 +1,174 @@
|
|||||||
|
---
|
||||||
|
slug: /1227/contributing
|
||||||
|
displayed_sidebar: europa
|
||||||
|
---
|
||||||
|
|
||||||
|
# Contributing to Dagger
|
||||||
|
|
||||||
|
The best way to find a good contribution is to use Dagger for something. Then write down what problems you encounter.
|
||||||
|
Could be as simple as a question you had, that the docs didn't answer. Or a bug in the tool, or a missing CUE package.
|
||||||
|
Then pick an item that you're comfortable with in terms of difficulty, and give it a try. 🙂
|
||||||
|
|
||||||
|
You can ask questions along the way, we're always happy to help you with your contribution. The bigger the contribution,
|
||||||
|
the earlier you should talk to maintainers to make sure you're taking the right approach and are not wasting your effort
|
||||||
|
on something that will not get merged.
|
||||||
|
|
||||||
|
## Package Style Guide
|
||||||
|
|
||||||
|
If you're contributing CUE packages, be sure to follow the [Package Coding Style](./1226-coding-style.md) guide as well.
|
||||||
|
|
||||||
|
## GitHub Workflow
|
||||||
|
|
||||||
|
The recommended workflow is to fork the repository and open pull requests from your fork.
|
||||||
|
|
||||||
|
### 1. Fork, clone & configure Dagger upstream
|
||||||
|
|
||||||
|
- Click on the _Fork_ button on GitHub
|
||||||
|
- Clone your fork
|
||||||
|
- Add the upstream repository as a new remote
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Clone repository
|
||||||
|
git clone https://github.com/$YOUR_GITHUB_USER/$REPOSITORY.git
|
||||||
|
|
||||||
|
# Add upstream origin
|
||||||
|
git remote add upstream git@github.com:dagger/$REPOSITORY.git
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Create a pull request
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Create a new feature branch
|
||||||
|
git checkout -b my_feature_branch
|
||||||
|
|
||||||
|
# Make changes to your branch
|
||||||
|
# ...
|
||||||
|
|
||||||
|
# Commit changes - remember to sign!
|
||||||
|
git commit -s
|
||||||
|
|
||||||
|
# Push your new feature branch
|
||||||
|
git push my_feature_branch
|
||||||
|
|
||||||
|
# Create a new pull request from https://github.com/dagger/$REPOSITORY
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Update your pull request with latest changes
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Checkout main branch
|
||||||
|
git checkout main
|
||||||
|
|
||||||
|
# Update your fork's main branch from upstream
|
||||||
|
git pull upstream main
|
||||||
|
|
||||||
|
# Checkout your feature branch
|
||||||
|
git checkout my_feature_branch
|
||||||
|
|
||||||
|
# Rebase your feature branch changes on top of the updated main branch
|
||||||
|
git rebase main
|
||||||
|
|
||||||
|
# Update your pull request with latest changes
|
||||||
|
git push -f my_feature_branch
|
||||||
|
```
|
||||||
|
|
||||||
|
## Scope of pull requests
|
||||||
|
|
||||||
|
We prefer small incremental changes that can be reviewed and merged quickly.
|
||||||
|
It's OK if it takes multiple pull requests to close an issue.
|
||||||
|
|
||||||
|
The idea is that each improvement should land in Dagger's main branch within a
|
||||||
|
few hours. The sooner we can get multiple people looking at and agreeing on a
|
||||||
|
specific change, the quicker we will have it out in a release. The quicker we
|
||||||
|
can get these small improvementes in a Dagger release, the quicker we can get
|
||||||
|
feedback from our users and find out what doesn't work, or what we have missed.
|
||||||
|
|
||||||
|
The added benefit is that this will force everyone to think about handling
|
||||||
|
partially implemented features & non-breaking changes. Both are great
|
||||||
|
approaches, and they work really well in the context of Dagger.
|
||||||
|
|
||||||
|
["Small incremental changes ftw"](https://github.com/dagger/dagger/pull/1348#issuecomment-1009628531) -> Small pull requests that get merged within hours!
|
||||||
|
|
||||||
|
## Commits
|
||||||
|
|
||||||
|
### DCO
|
||||||
|
|
||||||
|
Contributions to this project must be accompanied by a Developer Certificate of
|
||||||
|
Origin (DCO).
|
||||||
|
|
||||||
|
All commit messages must contain the Signed-off-by line with an email address
|
||||||
|
that matches the commit author. When commiting, use the `--signoff` flag:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git commit -s
|
||||||
|
```
|
||||||
|
|
||||||
|
The Signed-off-by line must match the **author's real name**, otherwise the PR will be rejected.
|
||||||
|
|
||||||
|
### Commit messages
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
[How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
|
||||||
|
:::
|
||||||
|
|
||||||
|
Guidelines:
|
||||||
|
|
||||||
|
- **Group Commits:** Each commit should represent a meaningful change (e.g. implement feature X, fix bug Y, ...).
|
||||||
|
- For instance, a PR should not look like _1) Add Feature X 2) Fix Typo 3) Changes to features X 5) Bugfix for feature X 6) Fix Linter 7)_ ...
|
||||||
|
- Instead, these commits should be squashed together into a single "Add Feature" commit.
|
||||||
|
- Each commit should work on its own: it must compile, pass the linter and so on.
|
||||||
|
- This makes life much easier when using `git log`, `git blame`, `git bisect`, etc.
|
||||||
|
- For instance, when doing a `git blame` on a file to figure out why a change
|
||||||
|
was introduced, it's pretty meaningless to see a _Fix linter_ commit message.
|
||||||
|
"Add Feature X" is much more meaningful.
|
||||||
|
- Use `git rebase -i main` to group commits together and rewrite their commit message.
|
||||||
|
- To add changes to the previous commit, use `git commit --amend -s`. This will
|
||||||
|
change the last commit (amend) instead of creating a new commit.
|
||||||
|
- Format: Use the imperative mood in the subject line: "If applied, this commit
|
||||||
|
will _your subject line here_"
|
||||||
|
- Add the following prefixes to your commit message to help trigger automated processes[^1]:
|
||||||
|
- `docs:` for documentation changes only (e.g., `docs: Fix typo in X`);
|
||||||
|
- `test:` for changes to tests only (e.g., `test: Check if X does Y`);
|
||||||
|
- `chore:` general things that should be excluded (e.g., `chore: Clean up X`);
|
||||||
|
- `website:` for the documentation website (i.e., the frontend code; e.g., `website: Add X link to navbar`);
|
||||||
|
- `ci:` for internal CI specific changes (e.g., `ci: Enable X for tests`);
|
||||||
|
- `infra:` for infrastructure changes (e.g., `infra: Enable cloudfront for X`);
|
||||||
|
|
||||||
|
[^1]: See [https://www.conventionalcommits.org](https://www.conventionalcommits.org)
|
||||||
|
|
||||||
|
## Docs
|
||||||
|
|
||||||
|
### Use relative links to markdown files
|
||||||
|
|
||||||
|
Link to markdown files (`[link](../foo.md)`) instead of relative URLs
|
||||||
|
(`[link](/foo)`).
|
||||||
|
|
||||||
|
The docs compiler will replace file links with relative URLs automatically.
|
||||||
|
|
||||||
|
This is to avoid broken links. If a file gets renamed, the compiler will
|
||||||
|
catch broken links and throw an error. Relative URLs get broken unnoticed.
|
||||||
|
|
||||||
|
## FAQ
|
||||||
|
|
||||||
|
### How to run the linter locally
|
||||||
|
|
||||||
|
To run all linters, from the repository root, run:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dagger do lint
|
||||||
|
```
|
||||||
|
|
||||||
|
### How to re-run all GitHub Actions jobs?
|
||||||
|
|
||||||
|
There isn't a button that Dagger contributors can click in their fork that will
|
||||||
|
re-run all GitHub Actions jobs. See issue
|
||||||
|
[#1669](https://github.com/dagger/dagger/issues/1169) for more context.
|
||||||
|
|
||||||
|
The current workaround is to re-create the last commit:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git commit --amend -s
|
||||||
|
|
||||||
|
# Force push the new commit to re-run all GitHub Actions jobs:
|
||||||
|
git push -f mybranch
|
||||||
|
```
|
@ -108,6 +108,8 @@ module.exports = {
|
|||||||
collapsible: false,
|
collapsible: false,
|
||||||
collapsed: false,
|
collapsed: false,
|
||||||
items: [
|
items: [
|
||||||
|
"guides/contributing",
|
||||||
|
"guides/coding-style",
|
||||||
"guides/container-images",
|
"guides/container-images",
|
||||||
"guides/cli-telemetry",
|
"guides/cli-telemetry",
|
||||||
"guides/docker-cli-load",
|
"guides/docker-cli-load",
|
||||||
@ -115,7 +117,6 @@ module.exports = {
|
|||||||
"guides/custom-buildkit",
|
"guides/custom-buildkit",
|
||||||
"guides/self-signed-certificates",
|
"guides/self-signed-certificates",
|
||||||
"guides/pushing-plan-dependencies",
|
"guides/pushing-plan-dependencies",
|
||||||
"guides/coding-style",
|
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
|
Reference in New Issue
Block a user