Submitting Changes - adobe/alloy GitHub Wiki

Signing the 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. You only need to submit an Adobe CLA one time, so if you have submitted one previously, you are good to go!

Contribution process

Web SDK accepts pull requests from other organizations within Adobe and from organizations and people outside of Adobe. The following process outlines how to work through contributions. For a small bug request, a simple Pull Request may be sufficient, but following this full process ensures good communication and understanding before work is commenced.

This is the same process that the Web SDK team follows internally. For approved changes from outside teams, a member of the Web SDK team will be assigned as the "Mentor" that will be the contact for all PR reviews, and ad-hoc questions.

1. Create a GitHub issue

Include the following sections:

  1. Context/Purpose - What problem are you trying to solve or what feature would you like to add? How does this relate to current customer needs?
  2. Background/Current workarounds - What would you have to do to make this work right now without the proposed changes? What are customers doing now that would be better with this change?
  3. Assumptions/Decisions - Assumptions that you have made or decisions about the design you would like feedback on. For example, "I'm assuming that customers will not need to change this setting after calling configure." or "Which of the following options make the most sense?"
  4. Proposed Design - Write this like the documentation that would be needed once the feature or change is implemented. It doesn't have to be polished prose fit for documentation. It can be bullet points. Be sure to include code snippets on how the library will work after the change. Also include changes to the Adobe Tags extension that will be required to support the change.
  5. Development Tasks - Break down the necessary code changes into the smallest releasable pieces. Include a plan for who will be doing the work and a rough timeline. Call out any dependencies on other teams.
  6. Test Plan - Include test-cases and steps for manual and automated tests. What setup is required for the test? What existing functionality could be affected by this change that we should verify?

As development on this feature continues and things change, be sure to keep this document updated.

2. Web SDK team to review

This may be most effective as a meeting. If within Adobe, schedule a meeting with the Web SDK engineers and product manager to review the issue, and give feedback. If outside of Adobe we can review the Github issue using comments on the issue or if something larger we can setup a meeting to discuss. Incorporate feedback from comments or the meeting into the design until the Web SDK team approves the change. At this point someone on the Web SDK team will be assigned as a "Mentor" to be the point of contact for questions and changes.

3. Documentation

Ideally, the issue description as outlined above can be the starting point for our doc writers. Include any additional information that doc writers will need such as which pages need updating, or which additional pages may be needed. Work with the Web SDK team to build documentation for the feature. This includes add in a JIRA ticket for the doc writers, and linking the GitHub issue. Ideally, do this once we are fairly confident in how the final design and UX will look like for library users and Adobe Tags extension users.

4. Code development

Any code changes should come in the form of pull requests which will need to be reviewed and approved by at least two project committers. Read GitHub's pull request documentation for more information on sending pull requests. Please follow the pull request template when submitting a pull request.

Ideally, break down the feature into small releasable changes that can be reviewed quickly and easily, merged quickly and released as monthly releases occur. Add PRs into main for these changes. Web SDK team will review the changes within a few days, and suggest changes.

For larger changes, create a feature branch off of main and push to Github. This will serve as the code staging ground that will eventually be merged into main when the whole feature is ready. Create small PRs that merge from another branch into the feature branch. Once approved these can be merged into the feature branch. Developing in this manner helps to correct invalid assumptions, and steer the development in the correct path. It is also difficult to give good attention to PRs that are dealing with many things at once.

5. Release

Web SDK follows a simple release system. When your feature or bug fix is ready, we merge it into main. Usually monthly or as needed, we will start the release process which consists of these steps:

  1. Look through existing PR and make sure everything is merged we would like to include in the release.
  2. Determine whether the changes warrant a major, minor, or patch increment to the release versions of the library and extension.
  3. Generate automated release notes for the new release using GitHub. (Create a new release, choose from a new tag, and then hit the "Generate Release Notes" button.) Do not save the release info the build process will do that. Remove any unnecessary release note items by going to the PR and adding the "ignore-for-release" tag to the PR. Update any PRs with titles that match what should go in the release notes. Send these release notes to the doc writers to include in the documentation.
  4. Build and release new versions of the library and extension with "-beta.0" affixed to the version number.Run the "deploy release" GitHub library workflow with "main" as the branch, and the full version number including "-beta.0" as the version. Update the version of the @adobe/alloy dependency in the extension with the new version, and then run the "deploy release" workflow on the extension. The extension changes are available in the "Unified JS Lab" org.
  5. Ensure automated tests pass, and run manual testing of all the new changes.
  6. Submit PRs for any problems, and merge them into main. This will trigger new builds with "-beta.1" version numbers.
  7. Once we are confident in the release (And not on a Friday), ask doc writers to merge documentation including release notes. Start the release process. Run the "deploy release" GitHub workflow using the version without "-beta.*". Approve the release in the action run. Once the library is successfully deployed, run the "deploy release" workflow on the extension without the "-beta.*" version. Once this is done, the deployment will be released privately. Have the Adobe Tags team review it, and publish it publicly. (You can find the extension ID in the action log).