From d92a43dbf8830bdf02ef4bab8240aceec96f59dc Mon Sep 17 00:00:00 2001 From: Scott Todd Date: Thu, 9 May 2024 15:08:13 -0700 Subject: [PATCH] Reorder contributing docs, add section for branch naming. --- .../docs/developers/general/contributing.md | 181 +++++------------- 1 file changed, 49 insertions(+), 132 deletions(-) diff --git a/docs/website/docs/developers/general/contributing.md b/docs/website/docs/developers/general/contributing.md index f65308aed59f..36d4547ae4ac 100644 --- a/docs/website/docs/developers/general/contributing.md +++ b/docs/website/docs/developers/general/contributing.md @@ -86,6 +86,29 @@ your current agreements on file or to sign a new one. one (even if it was for a different project), you probably don't need to do it again. +### :octicons-people-16: AUTHORS, CODEOWNERS, and MAINTAINERS + +The [`AUTHORS` file](https://github.com/iree-org/iree/blob/main/AUTHORS) keeps +track of those who have made significant contributions to the project. + +* If you would like additional recognition for your contributions, you may add + yourself or your organization (please add the entity who owns the copyright + for your contributions). +* The source control history remains the most accurate source for individual + contributions. + +The +[`.github/CODEOWNERS` file](https://github.com/iree-org/iree/blob/main/.github/CODEOWNERS) +lets maintainers opt in to PR reviews modifying certain paths. + +* Review is not required from a code owner, though it is recommended. + +The +[`MAINTAINERS.md` file](https://github.com/iree-org/iree/blob/main/MAINTAINERS.md) +documents official maintainers for project components. + +## :octicons-code-16: Coding policies + ### :octicons-pencil-16: Coding style guidelines Most of the code style is derived from the @@ -110,6 +133,16 @@ they are applied consistently across the project. [`build_tools/scripts/lint.sh`](https://github.com/iree-org/iree/blob/main/build_tools/scripts/lint.sh) can also be used to run the full suite of lint checks. +### :material-test-tube: Testing policy + +With few exceptions, features should be accompanied by automated tests. + +We use a mix of in-tree and out-of-tree unit and integration tests. For more +information about the types of tests used across the project, refer to the +[testing guide](./testing-guide.md). + +## :simple-github: GitHub policies + ### :octicons-code-review-16: Code reviews All submissions, including submissions by maintainers, require review. We @@ -124,14 +157,6 @@ information on using pull requests. working for a certain situation, please ask as we bias towards pragmatism for cases that require it. -### :material-test-tube: Testing policy - -With few exceptions, features should be accompanied by automated tests. - -We use a mix of in-tree and out-of-tree unit and integration tests. For more -information about the types of tests used across the project, refer to the -[testing guide](./testing-guide.md). - ### :material-check-all: GitHub Actions workflows We use [GitHub Actions](https://docs.github.com/en/actions) to automatically @@ -140,8 +165,9 @@ build and test various parts of the project. * Most presubmit workflows will only run automatically on PRs if you are a project collaborator. Otherwise a maintainer must [approve workflow runs](https://docs.github.com/en/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks). - If you are sending code changes to the project, please ask to be added as a - collaborator, so that these can run automatically. + If you are sending code changes to the project, please + [request commit access](#obtaining-commit-access), so that these can run + automatically. * It is generally expected that PRs will only be merged when all checks are passing. In some cases, pre-existing failures may be bypassed by a maintainer. @@ -151,9 +177,6 @@ build and test various parts of the project. [CI behavior manipulation](#ci-behavior-manipulation) section below to learn how to customize this behavior. - - - ### :octicons-git-pull-request-16: Merging approved changes After review and presubmit checks, PRs should typically be merged using @@ -192,18 +215,22 @@ join any of the teams on . [shark-infra](https://github.com/shark-infra/). Reach out to a project member if you would also like access to repositories in those organizations. -### :octicons-people-16: Credits in the AUTHORS file +### :octicons-git-branch-16: Branch naming -If you would like additional recognition for your contributions, you may add -yourself or your organization to the -[AUTHORS file](https://github.com/iree-org/iree/blob/main/AUTHORS) that keeps -track of those who have made significant contributions to the project. +Most work should be done on +[repository forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). +For developers with write access, when creating a branch in the common +[iree-org/iree repository](https://github.com/iree-org/iree), please follow +these naming guidelines: -* Please add the entity who owns the copyright for your contribution. -* The source control history remains the most accurate source for individual - contributions. +Branch type | Naming scheme | Example +-- | -- | -- +Single user | `users/[username]/*` | `users/cooldeveloper/my-awesome-feature` +Shared feature branch | `shared/*` | `shared/pytorch-performance-sprint` +Dependency updates | `integrates/*` | `integrates/integrate-llvm-20240501` - +Branches that do not meet these guidelines may be deleted, especially if +they [appear to be stale](https://github.com/iree-org/iree/branches/stale). ## Tips for contributors @@ -243,12 +270,6 @@ custom configurations such as accelerators. Configuration scripting is checked in to this repository (see the [README for that directory](https://github.com/iree-org/iree/blob/main/build_tools/github_actions/runner/README.md)). -#### Custom managed runners - -In addition to our self-hosted runners, we use GitHub's -[large managed runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-larger-runners) -for some platforms. - #### CI behavior manipulation The setup step of the CI determines which CI jobs to run. This is controlled by @@ -375,107 +396,3 @@ For example, this PR opted in to running the `build_test_all_windows` job: The enabled jobs can be viewed from the Summary page of an action run: ![ci_enabled_jobs](./contributing-ci-enabled-jobs.png) - -### Git workflows - -We tend to use the "triangular" or "forking" workflow. Develop primarily on a -clone of the repository on your development machine. Any local branches named -the same as persistent branches from the -[main repository](https://github.com/iree-org/iree) are pristine (though -potentially stale) copies. You only fastforward these to match upstream and -otherwise do development on other branches. When sending PRs, you push to a -different branch on your public fork and create the PR from there. - - - -#### Setup - -1. Create a fork of the main repository. - -2. Create a local git repository with remotes `upstream` (the main repository) - and `origin` (your personal fork). To list your current remotes - `git remote -v`. - - a. If you already cloned from the main repository (e.g. by following the - getting started guide): - - ```shell - # From your existing git repo - $ git remote rename origin upstream - $ git remote add origin https://github.com//iree.git - ``` - - b. If you haven't already cloned: - - ```shell - # From whatever directory under which you want to nest your repo - $ git clone https://github.com//iree.git - $ cd iree - $ git remote add upstream https://github.com/iree-org/iree.git - ``` - - This is especially important for maintainers who have write access (so can - push directly to the main repository) and admins who have elevated - privileges (so can push directly to protected branches). - - These names are just suggestions, but you might find some scripts where the - defaults are for remotes named like this. - - For extra safety, you can make it difficult to push directly to upstream by - setting the push url to something invalid: - `git remote set-url --push upstream DISABLE`, which requires re-enabling the - push URL explicitly before pushing. You can wrap this behavior in a custom - git command like - [git-sudo](https://gist.github.com/GMNGeoffrey/42dd9a9792390094a43bdb69659320c0). - -3. Use a script like - [git_update.sh](https://github.com/iree-org/iree/blob/main/build_tools/scripts/git/git_update.sh) - to easily synchronize `main` with `upstream`. Submodules make this is a - little trickier than it should be. You can also turn this into a git command - by adding it to your path as `git-update`. - -#### Git config - -These are some additional options you could put in your top-level `.gitconfig` -or repository-specific `.git/config` files that are conducive the recommended -workflow - - - -```ini -[push] - default = current -[alias] - # Delete branches that you pushed and have been deleted upstream, e.g. because - # the PR was merged. - gone = ! "git fetch -p && git for-each-ref --format '%(refname:short) %(upstream:track)' | awk '$2 == \"[gone]\" {print $1}' | xargs -r git branch -D" - # Update from upstream (custom command) and delete obsolete local branches. - sync = ! (git update main && git gone) - # Create a new branch based off of main (requires a clean working directory). - new = "!f(){ \\\ngit checkout main && git switch -c $1; \\\n}; f" - # Display branches in a useful "latest last" format - br = for-each-ref --sort=committerdate refs/heads/ --format='%(HEAD) %(color:yellow)%(refname:short)%(color:reset) - %(color:red)%(objectname:short)%(color:reset) - %(contents:subject) (%(color:green)%(committerdate:relative)%(color:reset))' - # `git git foo` -> `git foo` typo fixer - git = "!f(){ \\\n git \"$@\"; \\\n}; f" - # Get the git root directory - root = rev-parse --show-toplevel - # checkout, but also sync submodules - ch = "!f() { \\\n git checkout \"$@\"; git submodule sync && git submodule update --init; \\\n}; f" - # See the diff for a PR branch vs the main branch - diffmain = diff --merge-base main - # See only the files that differ vs the main branch - whatsout = diffmain --name-only -[checkout] - # If the checkout command - defaultRemote = origin -[pull] - # When pulling, only complete the pull if its a clean fast forward. - ff = only -[remote] - # Push to your fork (origin) by default - pushDefault = origin -[url "ssh://git@github.com/"] - # Pull with https (so no auth required), but push with ssh. - pushInsteadOf = https://github.com/ -```