Skip to content

Add external PR integration process and flowchart to CONTRIBUTING.md #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from
+114 −18
Open

Add external PR integration process and flowchart to CONTRIBUTING.md #43

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 114 additions & 18 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
## How to contribute to BLIS
## How to contribute to AOCL-BLAS

First, we want to thank you for your interest in contributing to BLIS! Please read through the following guidelines to help you better understand how to best contribute your potential bug report, bugfix, feature, etc.
First, we want to thank you for your interest in contributing to AOCL-BLAS! Please read through the following guidelines to help you better understand how to best contribute your potential bug report, bugfix, feature, etc.

#### **Did you find a bug?**

* **Check if the bug has already been reported** by searching on GitHub under [Issues](https://github.com/flame/blis/issues).
* **Check if the bug has already been reported** by searching on GitHub under [Issues](https://github.com/amd/blis/issues).

* If you can't find an open issue addressing the problem, please feel free to [open a new one](https://github.com/flame/blis/issues/new). Some things to keep in mind as you create your issue:
* If you can't find an open issue addressing the problem, please feel free to [open a new one](https://github.com/amd/blis/issues/new). Some things to keep in mind as you create your issue:
* Be sure to include a **meaningful title**. Aim for a title that is neither overly general nor overly specific.
* Putting some time into writing a **clear description** will help us understand your bug and how you found it.
* You are welcome to include the BLIS version number (e.g. 0.3.2-15) if you wish, but please supplement it with the **actual git commit number** corresponding to the code that exhibits your reported behavior (the first seven or eight hex digits is fine).
* Unless you are confident that it's not relevant, it's usually recommended that you **tell us how you configured BLIS** and **about your environment in general**. Your hardware microarchitecture, OS, compiler (including version), `configure` options, configuration target are all good examples of things to you may wish to include. If the bug involves elements of the build system such as bash or python functionality, please include those versions numbers, too.
* If your bug involves behavior observed after linking to BLIS and running an application, please provide a minimally illustrative **code sample** that developers can run to (hopefully) reproduce the error or other concerning behavior.
* You are welcome to include the AOCL-BLAS version number (e.g. 0.3.2-15) if you wish, but please supplement it with the **actual git commit number** corresponding to the code that exhibits your reported behavior (the first seven or eight hex digits is fine).
* Unless you are confident that it's not relevant, it's usually recommended that you **tell us how you configured AOCL-BLAS** and **about your environment in general**. Your hardware microarchitecture, OS, compiler (including version), `configure` options, configuration target are all good examples of things to you may wish to include. If the bug involves elements of the build system such as bash or python functionality, please include those versions numbers, too.
* If your bug involves behavior observed after linking to AOCL-BLAS and running an application, please provide a minimally illustrative **code sample** that developers can run to (hopefully) reproduce the error or other concerning behavior.

#### **Did you write a patch that fixes a bug?**

If so, great, and thanks for your efforts! Please submit a new GitHub [pull request](https://github.com/flame/blis/pulls) with the patch.
If so, great, and thanks for your efforts! Please submit a new GitHub [pull request](https://github.com/amd/blis/pulls) with the patch.

* Ensure the PR description clearly describes the problem and solution. Include any relevant issue numbers, if applicable.

* Please limit your PR to addressing one issue at a time. For example, if you are fixing a bug and in the process you find a second, unrelated bug, please open a separate PR for the second bug (or, if the bugfix to the second bug is not obvious, you can simply open an [issue](https://github.com/flame/blis/issues/new) for the second bug).
* Please limit your PR to addressing one issue at a time. For example, if you are fixing a bug and in the process you find a second, unrelated bug, please open a separate PR for the second bug (or, if the bugfix to the second bug is not obvious, you can simply open an [issue](https://github.com/amd/blis/issues/new) for the second bug).

* Before submitting new code, please read the [coding conventions](https://github.com/flame/blis/wiki/CodingConventions) guide to learn more about our preferred coding conventions. (It's unlikely that we will turn away your contributed code due to mismatched coding styles, but it will be **highly** appreciated by project maintainers since it will save them the time of digressing from their work--whether now or later--to reformat your code.)

Expand All @@ -33,15 +33,111 @@ If you are making a more substantial contribution and in the vicinity of the aff

That's fine, we are interested to hear your ideas!

* You may wish to introduce your idea by opening an [issue](https://github.com/flame/blis/issues/new) to describe your new feature, or how an existing feature is not sufficiently general-purpose. This allows you the chance to open a dialogue with other developers, who may provide you with useful feedback.
* You may wish to introduce your idea by opening an [issue](https://github.com/amd/blis/issues/new) to describe your new feature, or how an existing feature is not sufficiently general-purpose. This allows you the chance to open a dialogue with other developers, who may provide you with useful feedback.

* Before submitting new code, please read the [coding conventions](https://github.com/flame/blis/wiki/CodingConventions) guide to learn more about our preferred coding conventions. (See comments above regarding mismatched coding styles.)

#### **Do you have questions about the source code?**

* Feel free to ask questions on the [blis-devel mailing list](https://groups.google.com/d/forum/blis-devel). You'll have to join to post, but don't be shy! Most of the interesting discussion (outside of GitHub) happens on blis-devel. We also have a [blis-discuss mailing list](https://groups.google.com/d/forum/blis-discuss), but it is not the preferred venue for discussion these days.

Here at the BLIS project, we :heart: our community. :) Thanks for helping to make BLIS better!

Field

#### How are external pull requests integrated?

This document outlines the process for handling external contributions to the AOCL-BLAS project, ensuring quality, transparency, and timely communication with contributors. The workflow covers PR validation, review, internal integration, and contributor notification.

**Process Overview:**

1. PR Submission:
- External contributors submit a PR to the `dev` branch of the public repository: **https://github.com/amd/blis.git**.

2. Initial CI/CD Validation:
- A CI/CD job runs on a Linux Docker container to check for Coverity (static analysis) issues.

3. Coverity Report Review:
- The reviewer examines the Coverity report.
- If issues are found, the PR is rejected, and details are communicated to the contributor via GitHub comments.
- If there are no issues, the reviewer approves the Coverity check via the CI/CD URL received by email.

4. Presubmit CI/CD Jobs:
- Upon approval, presubmit (sanity) tests are triggered.
- Reviewers receive email notifications about the job status.

5. Presubmit Results Review:
- If tests fail, the PR is rejected, and the contributor is notified via GitHub comments with relevant details.
- If tests pass, the reviewer approves PR.

6. Internal Repository Integration:
- The approved PR is ported to the AOCL-BLAS internal GitHub repository, preserving the contributor's name and email.

7. Internal Validation:
- The PR undergoes regular internal CI/CD validations.
- If issues are found, they are reported to the contributor via the external GitHub comment section.
- If there are no issues, the PR is merged into the internal repository.

8. Release and Notification:
- Merged changes are included in the subsequent open-source release (dev branch).
- Contributors are notified via GitHub comments once their changes are merged.
- Any issues found during internal release candidate (RC) or test cycles are handled by the internal team.

**Flow Diagram Description:**

```
[External Contributor]
|
v
[Submit PR to Public Repo (dev branch)]
|
v
[CI/CD: Coverity Scan]
|
v
[Review Coverity Report]
/ \
[Issues] [No Issues]
| |
v v
[Reject PR] [Approve Coverity]
| |
v |
[Notify Contributor] |
v
[CI/CD: Presubmit Tests]
|
v
[Review Presubmit Results]
/ \
[Fail] [Pass]
| |
v v
[Reject PR] [Approve PR]
| |
v |
[Notify Contributor] |
v
[Port PR to Internal Repo]
|
v
[Internal CI/CD Validations]
/ \
[Fail] [Pass]
| |
v v
[Notify Contributor] [Merge PR]
|
v
[Weekly Release to Public Repo]
|
v
[Notify Contributor of Merge]
```

**Communication:**

- All rejection reasons and validation results are communicated to contributors via GitHub comments.
- Contributors are notified when their changes are merged and released.

**Notes:**

- Contributor attribution (name and email) is preserved during internal integration.
- Internal team is responsible for post-merge issue resolution during RC and test cycles.
- The internal team will act as reviewers and have the authority to either approve or reject pull requests (PRs).

Here at the AOCL-BLAS project, we :heart: our community. Thanks for helping to make AOCL-BLAS better:blush:!

— The AMD AOCL-BLAS Team
Loading