From 88d78a963dc5e72bdea6c92d186979583fa6350f Mon Sep 17 00:00:00 2001 From: Gerhard Lazu Date: Thu, 20 Jan 2022 16:29:07 +0000 Subject: [PATCH] Use CONTRIBUTING from our org Rather than having multiple CONTRIBUTING files, one for each repository, which we will need to keep in sync, we could use GitHub's special .github repository for community files. This idea was first reported by @bpo in the context of the examples repository: https://github.com/dagger/examples/pull/47#issuecomment-1012517202 I have added it as https://github.com/dagger/.github and explained how the contributing flow now changed for first-time contributors to *any* repository in our org: https://github.com/dagger/examples/pull/47#issuecomment-1013450052 There is more info on this feature here: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file We could continue by adding CODE_OF_CONDUCT, SECURITY etc. files and all our repositories will use them, without needing to add these files to each repository. Is this a GitHub feature something that fits us? Signed-off-by: Gerhard Lazu --- CONTRIBUTING.md | 143 ----------------------------- README.md | 2 +- docs/learn/1004-first-env.md | 8 +- docs/learn/1010-dev-cue-package.md | 2 +- 4 files changed, 6 insertions(+), 149 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f2a2c1d7..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,143 +0,0 @@ -# Contributing to Dagger - -## GitHub Workflow - -The recommended workflow is to clone the repository from `dagger/dagger` and -open pull requests from your own fork. - -### 1) Cloning the repository - -```sh -git clone https://github.com/dagger/dagger.git -``` - -**NOTE**: If you cloned your fork, either switch back to `dagger/dagger` using -`git remote` or start over. - -### 2) Forking - -- Click on the _Fork_ button on GitHub -- Add your fork as a remote - -```sh -git remote add fork git@github.com:MYFORK/dagger.git -``` - -### 3) Creating a Pull Request - -```sh -# create a branch -git checkout -b mybranch - -# make changes to your branch, use `git commit -s`, ... -# ... - -# push the branch to your own fork -git push -u fork mybranch - -# create a pull request from https://github.com/dagger/dagger -``` - -### 4) Rebasing - -```sh -git checkout main -git pull # <-- this will pull from `dagger/dagger` -git checkout mybranch -git rebase main # <-- this will rebase `dagger/dagger` into your `FORK/dagger` -git push -f -u fork mybranch # <-- update the pull request -``` - -## 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 -approached, 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: - -```sh -git commit -s -``` - -The Signed-off-by line must match the **author's real name**, otherwise the PR will be rejected. - -### Commit Messages - -[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_" - -## 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 markdown linter locally - -First install `markdownlint-cli`: - -- On Mac OS: `brew install markdownlint-cli` -- On other systems, with yarn installed: `yarn global add markdownlint-cli` - -Then from the repository root: - -```console -markdownlint -c .markdownlint.yaml docs/**/*.md -``` - -### How to retrigger a Github Action workflow? - -There isn't a button that Dagger contributors can click in their fork of Dagger that will trigger a GitHub Action workflow run. See issue [#1669](https://github.com/dagger/dagger/issues/1169) for more context. - -The current workaround is to force push to your fork: - -```bash -➜ # Apply a small change to a comment -➜ git add --all -➜ make lint # Make sure that the linter is happy :) -➜ git commit --signoff --amend -➜ git push --force -``` diff --git a/README.md b/README.md index 44a6cf33..1ffafc33 100644 --- a/README.md +++ b/README.md @@ -26,4 +26,4 @@ Using Dagger, software teams can develop powerful CICD pipelines with minimal ef * [Join the Dagger community on Discord](https://discord.gg/ufnyBtc8uY) * [Install from a binary release](https://docs.dagger.io/1001/install/) * [Build from source](https://docs.dagger.io/1001/install/#option-4-install-from-source) -* [How to contribute](CONTRIBUTING.md) +* [How to contribute](https://github.com/dagger/.github/blob/main/CONTRIBUTING.md) diff --git a/docs/learn/1004-first-env.md b/docs/learn/1004-first-env.md index ca400f06..7f57dc1e 100644 --- a/docs/learn/1004-first-env.md +++ b/docs/learn/1004-first-env.md @@ -239,18 +239,18 @@ dagger up -e multibucket ### Using the environment -[This section is not yet written](https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md) +[This section is not yet written](https://github.com/dagger/.github/blob/main/CONTRIBUTING.md) ## Share your environment ### Introduction to gitops -[This section is not yet written](https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md) +[This section is not yet written](https://github.com/dagger/.github/blob/main/CONTRIBUTING.md) ### Review changes -[This section is not yet written](https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md) +[This section is not yet written](https://github.com/dagger/.github/blob/main/CONTRIBUTING.md) ### Commit changes -[This section is not yet written](https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md) +[This section is not yet written](https://github.com/dagger/.github/blob/main/CONTRIBUTING.md) diff --git a/docs/learn/1010-dev-cue-package.md b/docs/learn/1010-dev-cue-package.md index 111d3509..ac737c05 100644 --- a/docs/learn/1010-dev-cue-package.md +++ b/docs/learn/1010-dev-cue-package.md @@ -106,4 +106,4 @@ You've probably seen it when you've initialized your project: ``` We are still a small community and are constantly looking for new contributors that will work with us to improve this fantastic project. If you feel like we are missing a package or want to improve an existing one, please start with our -[contributing docs](https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md) and open a PR. +[contributing docs](https://github.com/dagger/.github/blob/main/CONTRIBUTING.md) and open a PR.