Merge remote-tracking branch 'upstream/dev' into 758

Saira-A · Nov 25, 2024 · 54d0ff7 · 54d0ff7
2 parents 5598fad + f89cf01
commit 54d0ff7
Show file tree

Hide file tree

Showing 4 changed files with 765 additions and 4,243 deletions.
diff --git a/COMMUNITY_TEAM.md b/COMMUNITY_TEAM.md
@@ -1,33 +1,37 @@
 # UV Community Team
 
-UV community team members help shepherd the community. They are here to help mentor newcomers, review pull requests, and facilitate issue discussions.
+The Universal Viewer [Governance Document](https://github.com/UniversalViewer/universalviewer/blob/dev/GOVERNANCE.md) explains how the project's open source community operates.
 
-## Primary Role Descriptions
-
-### Supporting Success of the Project & Its Contributors
+The [Contribution Guide](https://github.com/UniversalViewer/universalviewer/blob/dev/CONTRIBUTING.md) explains some of the more technical aspects of participating in the project.
 
-- Responding to newcomer questions in [Slack](http://universalviewer.io/#contact) and on GitHub.
-- Helping select tasks for newcomers or other community members who are unsure of where to start.
-- Reviewing pull requests, with a goal of three (3) reviews per PR.
-- Where possible, helping bring a PR to a final acceptable state, based on engineering review.
-- Providing useful feedback in issues.
+All community members are expected to adhere to the project's [Code of Conduct](https://github.com/UniversalViewer/universalviewer/blob/dev/CODE_OF_CONDUCT.md).
 
-### Building a Healthy and Inclusive Community
+This page expands upon some specific roles that members of the community may wish to take on.
 
-- Leading by example, through adherence to [Mozilla's Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) ("CPG").
-- [Looking for and reporting any violations of the Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/reporting/).
-- Ensuring opportunities for all levels of contribution, confidence, and background.
+## Primary Role Descriptions
 
 ### Active Community Team Members
 
 Active Community Members are visibly active in our Slack and/or GitHub channels. We identify active members as being those whom contributors and staff can most count on for a response within 2-3 days.
 
+These individuals are willing and able to help with some or all of the following tasks:
+
+- Responding to newcomer questions in [Slack](http://universalviewer.io/#contact) and on GitHub.
+- Helping select tasks for newcomers or other community members who are unsure of where to start.
+- Reviewing pull requests.
+- Where possible, helping bring a PR to a final acceptable state, based on engineering review.
+- Providing useful feedback in issues.
+
 |                                                                       | (Ordered alphabetically, by first name)                                                                                                                                                                                                                              |
 | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ![Demian](https://avatars.githubusercontent.com/demiankatz?s=460&v=4) | **[Demian](https://github.com/demiankatz)** is Director of Library Technologies and has been at Falvey Memorial Library in some capacity since 2009, living in Philadelphia US. Ask Demian about: <ul><li>Universal Viewer</li><li>TypeScript</li><li>IIIF</li></ul> |
+| ![Demian](https://avatars.githubusercontent.com/demiankatz?s=460&v=4) | **[Demian](https://github.com/demiankatz)** is Director of Library Technologies and has been at Villanova University's Falvey Library in some capacity since 2009, living near Philadelphia in the US. Ask Demian about: <ul><li>Universal Viewer</li><li>TypeScript</li><li>IIIF</li></ul> |
 | ![Edward](https://avatars.githubusercontent.com/edsilv?s=460&v=4)     | **[Edward](https://github.com/edsilv)** is an applications developer at [mnemoscene](https://mnscene.io), living in Brighton UK. Ask Edward about: <ul><li>React</li><li>three.js</li><li>Universal Viewer</li><li>TypeScript</li><li>IIIF</li></ul>                 |
 
-### Joining the Team
+### Translation Team
+
+The Universal Viewer's interface has been translated into several languages. If you have language skills and would like to assist in adding support for a new language or helping to maintain an existing one, please join the #translations channel in the project's Slack.
+
+## Joining the Team
 
 We welcome active contributors to join the UV team. Specifically, we are looking for contributors with:
 
@@ -37,8 +41,6 @@ We welcome active contributors to join the UV team. Specifically, we are looking
 
 To apply, simply contact one of our staff or community team members via Slack or email, and we'll get right back to you.
 
-We embrace diversity, and invite people from any and all backgrounds to get involved in the UV project. We don't discriminate based on family status, gender, gender-identity, marital status, sexual orientation, sex, age, ability, race and/or ethnicity, national origin, socioeconomic status, religion, geographic location, or any other dimension of diversity.
-
 ### Review Periods
 
-Once per year, we'll check in with our team members (both _active_ and _on break_) to ensure they are feeling supported, and to check if they will remain active on our team for the coming months. If we do not hear back from members at check-in time, they will be transitioned to an alumni role.
+Once per year, we'll check in with our team members (both _active_ and _on break_) to ensure they are feeling supported, and to check if they will remain active on our team for the coming months. If we do not hear back from members at check-in time, they will be transitioned to an alumni role. Alumni will be acknowledged here as thanks for their past service and are still welcome to participate in the community, but they are no longer expected to respond quickly to inquiries or meet other specific standards of community service. Alumni can have their names entirely removed from the list by request.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -56,7 +56,7 @@ Before commiting your changes make sure tests are passing:
 npm test
 ```
 
-> Note: the development server must be running (`npm start`)
+> Note: the test suite runs its own server on port 4444 for browser-based testing; be sure that you have built the latest code (e.g. using `npm run build`) before running tests to ensure that you are testing the right changes.
 
 > Tests are written using [Jest](https://jestjs.io/)
 
@@ -68,6 +68,8 @@ This project follows the [Gitflow workflow](https://www.atlassian.com/git/tutori
 - Completed features should be merged into the dev branch, which represents the bleeding edge of stable development.
 - When a release is made, the dev branch is merged into the main branch. Main represents the most recent release of the project.
 
+The project also makes use of `release-X.Y` branches to track previous lines of development; see the release process below for more details.
+
 Please target the dev branch when opening pull requests against the project.
 
 ### Creating a branch and committing
@@ -89,22 +91,29 @@ After pushing your new branch to your fork, you can create a PR; see: https://gu
 
 ## Creating a release
 
-The decision to make a new release should be made by the Universal Viewer Steering Group. Once a release is planned, the appropriate commit from the dev branch should be merged into the main branch.
+### Release Candidate Process
 
-Next, checkout the `main` branch, and ensure it is up-to-date.
+Before a release can be made, some planning and testing are required:
 
-Run `npm version [major | minor | patch]` to apply an appropriate [semantic versioning](https://semver.org/) update; for example:
+1. The [Universal Viewer Steering Group](https://github.com/UniversalViewer/universalviewer/wiki/Steering-Group) is responsible for determining when a new release is needed (for example, because a sprint has completed, or because a major fix or feature has been contributed) and for identifying a Release Manager (any Steering Group member with rights to bypass GitHub branch protection rules) to manage the technical parts of the process. The community is welcome to reach out to members of the Steering Group to propose/request a release at any time.
+2. Once a release is decided upon, its version number must be determined. The project uses [semantic versioning](https://semver.org/), so given version X.Y.Z, we will increment Z for fixes (patch release), Y for new features (minor release), or X for backward-incompatible changes (major release).
+3. If outstanding work must be completed to ensure a stable release, a milestone for the new version will be created in GitHub and all relevant outstanding issues/PRs assigned to it, so that estimation can be performed to set a realistic release date (this could be done at steering group and/or community call meetings). If work is already complete, the release can proceed immediately.
+4. When it's time to begin the release process, the Release Manager will create a pull request against the `dev` branch containing the result of running the `npm version X.Y.Z-rc1` command (where X.Y.Z is replaced with the new version determined in step 2). This will create a release candidate that can be easily tested online and/or locally built. The description of this pull request should highlight major changes and areas where testing is needed.
+5. Once the release candidate is built, the Steering Group will announce it and offer an appropriate testing window (usually 1-2 weeks, depending on scope/complexity of changes) for community feedback. During this window, community members are encouraged to build the new version, try it out in their environments, and raise issues/pull requests if they encounter problems.
+6. When the testing window ends, the pull request from step 4 will be merged.
+7. If problems were found during the testing window, they will be evaluated by the Steering Group, and as soon as any critical bugs are fixed, steps 4-6 will be repeated with an incremented "rc" number (e.g. X.Y.Z-rc2) to ensure that no problems remain.
+8. Once the release candidate is deemed stable by the Steering Group, it will be promoted to the formal release. After the RC pull request is merged, the full release can be published.
 
-```bash
-npm version patch
-```
+### Making a Normal Release
 
-This will update the `package.json` version and create a git tag. Then push both the main/tag.
+Once a stable release is ready to be published, these steps can be followed by the Release Manager:
 
-```bash
-git push origin main v0.0.8
-```
+1. On the `dev` branch, run `npm version X.Y.Z` (replacing "X.Y.Z" with the actual number of the new version) to appropriately update `package.json` and create a git tag.
+2. If the new release will be a major or minor version (but NOT if it will be a patch release), a new `release-X.Y` branch needs to be created from the `main` branch before anything is merged. This release branch will make it easier to backport fixes to earlier versions if critical bugs or security issues are discovered later. For example, if the current version is 4.0.25 and 4.1.0 is about to be released, a new `release-4.0` branch would be created from the `main` branch to continue tracking the development of the 4.0.x line of code.
+3. Whether or not a release branch needed to be created, it is now time to merge the `dev` branch into the `main` branch to ensure that `main` always represents the most recently released version.
+4. All changed branches and newly-created release tags must be pushed to GitHub; e.g. `git push origin main dev v4.1.0 release-4.0` (for a new major release) or `git push origin main dev v4.1.1` (for a new minor release).
+5. At this point, a GitHub action will recognize the new version tag and publish the package to NPM.
 
-Then the GitHub action will pick up the tag and publish it to NPM.
+### Backporting a Bug Fix
 
-Finally, merge the `main` branch back to the `dev` branch to synchronize the version numbers.
+If there is a need to fix a bug in an older version of the code, bug fix pull requests should be created against the appropriate `release-X.Y` branch(es). After these are merged and tested, releases can be published from the appropriate release branch(es) by running `npm version patch` and then pushing the updated files and new release tag to GitHub. There should be no need to merge from `release-X.Y` branches forward to the `dev` branch when fixes are backported.