From 792edcc34732522d1a46ca26580878fcb7af01a5 Mon Sep 17 00:00:00 2001 From: Joe Khoury Date: Sun, 22 Oct 2023 12:54:20 -0400 Subject: [PATCH 1/4] Create CONTRIBUTING.md --- CONTRIBUTING.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..76c791bdc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing + +We welcome pull requests from everyone. πŸŽ‰ + +The following are a set of guidelines to follow when contributing to this project. + +Our guidelines differ based on the type of change you are submitting: New feature vs Enhancement & Bug fix. + + +## Contributor license agreement + +All third-party contributions to this project must be accompanied by a signed contributor +license agreement. This gives Adobe permission to redistribute your contributions +as part of the project. [Sign our CLA](http://opensource.adobe.com/cla.html). You +only need to submit an Adobe CLA one time, so if you have submitted one previously, +you are good to go! + + +## Bug Fix Process + +All submissions should come in the form of pull requests and need to be reviewed by the AEP Web SDK's Core team. + +Describe the bug you are fixing, and list the steps to reproduce it. + + +## New Feature Process + +Every new feature change starts with a technical/prd document. + +If you are an internal contributor, start by creating a Wiki and reach out to the AEP Web SDK's Product team to discuss your proposal. + +If you are an external contributor, start by creating a Github issue and describing your feature in details. Assign the ticket to https://github.com/jfkhoury. + +Once the feature has been approved by Product, here what happens next: + +- Add detailed architecture and design to the technical document. (This document will be shared with the doc writers at Adobe, so make it as detailed as possible) +- Share your changes with the AEP Web SDK team for design discussions and approval. +- Once the design has been approved, you can go ahead and start the development work, while we share the technical doc with the writers for public documentation. +- Break down your PR into manageable and readable PRs, and multiple clear commits. +- You need 3 approvals from the Core Web SDK team to get your PR approved. +- If you and the Core team cannot agree over a specific concern with the code, Joe (https://github.com/jfkhoury) will be the tie breaker. + - We encourage and enjoy open minded, deep discussions on this team. Try your best to propose a design that the whole team agrees with. + + +## Pull Request Approval Process + +We do our best to keep on top of all the pull requests. We may suggest some changes, improvements or alternatives. + +Things to add to your pull request: + +- Write a thorough pull request description, include screenshots. Describe your bug fix and why it's needed/important in the pull request description. +- Write out your test cases in as much detail as possible. PRs without tests will not be reviewed. +- Make sure the PR merges cleanly with the latest main. +- 3 approvals from the Web SDK core team are required to consider your PR approved. + + From a1dc8466228ef279e21fd8d6a948c630b8fa5277 Mon Sep 17 00:00:00 2001 From: Joe Khoury Date: Sun, 22 Oct 2023 12:59:56 -0400 Subject: [PATCH 2/4] Update CONTRIBUTING.md to explain ownership --- CONTRIBUTING.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76c791bdc..22f590f55 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,7 @@ If you are an internal contributor, start by creating a Wiki and reach out to th If you are an external contributor, start by creating a Github issue and describing your feature in details. Assign the ticket to https://github.com/jfkhoury. -Once the feature has been approved by Product, here what happens next: +#### Once the feature has been approved by Product, here what happens next: - Add detailed architecture and design to the technical document. (This document will be shared with the doc writers at Adobe, so make it as detailed as possible) - Share your changes with the AEP Web SDK team for design discussions and approval. @@ -40,6 +40,17 @@ Once the feature has been approved by Product, here what happens next: - You need 3 approvals from the Core Web SDK team to get your PR approved. - If you and the Core team cannot agree over a specific concern with the code, Joe (https://github.com/jfkhoury) will be the tie breaker. - We encourage and enjoy open minded, deep discussions on this team. Try your best to propose a design that the whole team agrees with. + +#### Ownership + +As a contributor, you are not expected to own this feature in case there were bugs or enhancement requests in the future. + +The AEP Web SDK core team will own it. For this to work though, we need few things from you: + +- As mentioned in the previous section, we need a detailed technical documents explaining the feature and architecture. +- We need to have as many conversations as needed by the AEP Web SDK core team to fully understand and approve the design. +- We need to have as many conversations as needed by the AEP Web SDK core team to fully understand and approve the code. + ## Pull Request Approval Process From 32e07a1c9e44738dec4fe58ae9add0aadd8104ae Mon Sep 17 00:00:00 2001 From: Joe Khoury Date: Sun, 22 Oct 2023 13:21:37 -0400 Subject: [PATCH 3/4] Update README to link to the contribution doc. --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 600eb955c..0b2607ffb 100644 --- a/README.md +++ b/README.md @@ -8,4 +8,7 @@ Alloy is the code name for the Adobe Experience Platform Web SDK. It allows for For documentation on how to use Alloy, please see the [user documentation](https://experienceleague.adobe.com/docs/experience-platform/edge/home.html). -For documentation on how to contribute to Alloy, please see the [developer documentation](https://github.com/adobe/alloy/wiki). + +## Contribution + +Check out the [contribution guidelines](https://github.com/adobe/alloy/CONTRIBUTION.md) for quick start information, and head over to the [developer documentation](https://github.com/adobe/alloy/wiki) to understand the architecture and structure of the library. \ No newline at end of file From 33bf70bb7b53c28c0deab3e216be99942c7c8959 Mon Sep 17 00:00:00 2001 From: Joe Khoury Date: Fri, 27 Oct 2023 06:27:26 -0400 Subject: [PATCH 4/4] rewrite for clarity and add more details --- CONTRIBUTING.md | 65 ++++++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22f590f55..46efee732 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,10 @@ # Contributing -We welcome pull requests from everyone. πŸŽ‰ +Welcome to the home of the AEP Web SDK! We appreciate your interest in contributing and are excited to collaborate. -The following are a set of guidelines to follow when contributing to this project. +The following guidelines will help ensure a smooth contribution process. -Our guidelines differ based on the type of change you are submitting: New feature vs Enhancement & Bug fix. +Our guidelines vary depending on the type of contribution: New Feature, Enhancement, or Bug Fix. ## Contributor license agreement @@ -18,50 +18,53 @@ you are good to go! ## Bug Fix Process -All submissions should come in the form of pull requests and need to be reviewed by the AEP Web SDK's Core team. +Submit bug fixes via pull requests, to be reviewed by the AEP Web SDK's Core team. -Describe the bug you are fixing, and list the steps to reproduce it. +1. Create a pull request. +2. Describe the bug, and provide steps to reproduce it. (More details on the PR process below) ## New Feature Process -Every new feature change starts with a technical/prd document. +New feature contributions start with a Concept Approval (CA) / Proposal document. -If you are an internal contributor, start by creating a Wiki and reach out to the AEP Web SDK's Product team to discuss your proposal. +- Internal Contributors: Create a Wiki page and engage with the AEP Web SDK's Product team to discuss your proposal. +- External Contributors: Create a GitHub issue detailing your feature and assign the ticket to https://github.com/jfkhoury. +- No need for detailed architectural insights at this stage. -If you are an external contributor, start by creating a Github issue and describing your feature in details. Assign the ticket to https://github.com/jfkhoury. -#### Once the feature has been approved by Product, here what happens next: +#### Post Approval -- Add detailed architecture and design to the technical document. (This document will be shared with the doc writers at Adobe, so make it as detailed as possible) -- Share your changes with the AEP Web SDK team for design discussions and approval. -- Once the design has been approved, you can go ahead and start the development work, while we share the technical doc with the writers for public documentation. -- Break down your PR into manageable and readable PRs, and multiple clear commits. -- You need 3 approvals from the Core Web SDK team to get your PR approved. -- If you and the Core team cannot agree over a specific concern with the code, Joe (https://github.com/jfkhoury) will be the tie breaker. - - We encourage and enjoy open minded, deep discussions on this team. Try your best to propose a design that the whole team agrees with. - -#### Ownership - -As a contributor, you are not expected to own this feature in case there were bugs or enhancement requests in the future. +1. Add a thorough architecture and design proposal to a technical document. + - Seek assistance from the AEP Web SDK Engineering team for design input if necessary. + - This document will be shared with Adobe's documentation writers, so ensure it's detailed. +2. Share your CA and technical documents with the AEP Web SDK engineering team for further discussion and approval. + - A work session will be scheduled for a kickoff discussion. (Joe to set up) +3. Upon design approval, proceed with development. The technical document will be shared with the documentation team for public documentation preparation. -The AEP Web SDK core team will own it. For this to work though, we need few things from you: -- As mentioned in the previous section, we need a detailed technical documents explaining the feature and architecture. -- We need to have as many conversations as needed by the AEP Web SDK core team to fully understand and approve the design. -- We need to have as many conversations as needed by the AEP Web SDK core team to fully understand and approve the code. +## Pull Request Approval Process +We strive to review all pull requests promptly and may suggest improvements or alternatives. +Include in your pull request: -## Pull Request Approval Process -We do our best to keep on top of all the pull requests. We may suggest some changes, improvements or alternatives. +- Break down your PR into manageable commits and add a descriptive PR title and thorough description, including screenshots if applicable. +- Ensure code adheres to our formatting and usage standards (`npm run format` and `npm run lint`) +- Testing: + - Detail your test cases comprehensively. PRs lacking tests will not be reviewed. + - Include unit and functional tests. + - Test your feature in the [Sandbox](https://github.com/adobe/alloy/wiki/Running-the-sandbox-locally-over-HTTPS-on-Mac-OS). +- Make sure the PR merges cleanly with the latest main. +- Obtain 3 approvals from the Core Web SDK team to have your PR approved. +- If a consensus isn’t reached regarding any code concern, Joe will provide the final say. + - We encourage and enjoy open minded, deep discussions on this team. Try your best to propose a design that the whole team agrees with. -Things to add to your pull request: -- Write a thorough pull request description, include screenshots. Describe your bug fix and why it's needed/important in the pull request description. -- Write out your test cases in as much detail as possible. PRs without tests will not be reviewed. -- Make sure the PR merges cleanly with the latest main. -- 3 approvals from the Web SDK core team are required to consider your PR approved. +## Ownership +While contributors are not expected to maintain the feature post-contribution, for a smooth handover, we require: +- Detailed technical documents explaining the feature and architecture. +- Engage in discussions with the AEP Web SDK core team to ensure full understanding and approval of the design and code.