You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
UV community team members help shepherd the community. They are here to help mentor newcomers, review pull requests, and facilitate issue discussions.
3
+
The Universal Viewer [Governance Document](https://github.com/UniversalViewer/universalviewer/blob/dev/GOVERNANCE.md) explains how the project's open source community operates.
4
4
5
-
## Primary Role Descriptions
6
-
7
-
### Supporting Success of the Project & Its Contributors
5
+
The [Contribution Guide](https://github.com/UniversalViewer/universalviewer/blob/dev/CONTRIBUTING.md) explains some of the more technical aspects of participating in the project.
8
6
9
-
- Responding to newcomer questions in [Slack](http://universalviewer.io/#contact) and on GitHub.
10
-
- Helping select tasks for newcomers or other community members who are unsure of where to start.
11
-
- Reviewing pull requests, with a goal of three (3) reviews per PR.
12
-
- Where possible, helping bring a PR to a final acceptable state, based on engineering review.
13
-
- Providing useful feedback in issues.
7
+
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).
14
8
15
-
### Building a Healthy and Inclusive Community
9
+
This page expands upon some specific roles that members of the community may wish to take on.
16
10
17
-
- Leading by example, through adherence to [Mozilla's Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) ("CPG").
18
-
-[Looking for and reporting any violations of the Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/reporting/).
19
-
- Ensuring opportunities for all levels of contribution, confidence, and background.
11
+
## Primary Role Descriptions
20
12
21
13
### Active Community Team Members
22
14
23
15
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.
24
16
17
+
These individuals are willing and able to help with some or all of the following tasks:
18
+
19
+
- Responding to newcomer questions in [Slack](http://universalviewer.io/#contact) and on GitHub.
20
+
- Helping select tasks for newcomers or other community members who are unsure of where to start.
21
+
- Reviewing pull requests.
22
+
- Where possible, helping bring a PR to a final acceptable state, based on engineering review.
||**[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> |
27
+
||**[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> |
28
28
||**[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> |
29
29
30
-
### Joining the Team
30
+
### Translation Team
31
+
32
+
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.
33
+
34
+
## Joining the Team
31
35
32
36
We welcome active contributors to join the UV team. Specifically, we are looking for contributors with:
33
37
@@ -37,8 +41,6 @@ We welcome active contributors to join the UV team. Specifically, we are looking
37
41
38
42
To apply, simply contact one of our staff or community team members via Slack or email, and we'll get right back to you.
39
43
40
-
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.
41
-
42
44
### Review Periods
43
45
44
-
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.
46
+
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.
1. On the command line, go in to the `universalviewer` folder
21
+
1. On the command line, navigate to the `universalviewer` folder:
22
22
23
-
`cd universalviewer`
23
+
`cd universalviewer`
24
24
25
-
1.Run
25
+
1.To install dependencies, run:
26
26
27
27
`npm install`
28
28
@@ -34,35 +34,53 @@ To build the debug version of the viewer, just run (on the command line, in the
34
34
35
35
This will compile the project using webpack and serve the examples on `localhost:8080`
36
36
37
-
## Distribution Builds
37
+
## Building for distribution
38
38
39
39
To build the distribution version of the UV, just run (on the command line, in the `universalviewer` folder):
40
40
41
41
npm run build
42
42
43
-
#### 2. Open `universalviewer` folder in your IDE
43
+
When this process completes, your build can be found in the `dist` folder under your `universalviewer` folder.
44
+
45
+
## Code Architecture
44
46
45
47
UV source code lives inside the `/src/` folder.
46
48
47
49
Here is a [diagram](https://docs.google.com/drawings/d/1i484Jd32FoLwtE5uvkBA6l5LV-DioSOZDIWD0WfhWl8/edit?usp=sharing) showing the overall architecture of the project.
48
50
49
-
#### 3. Run test suite
51
+
##Running the test suite
50
52
51
53
Before commiting your changes make sure tests are passing:
52
54
53
55
```
54
56
npm test
55
57
```
56
58
57
-
> Note: the development server must be running (`npm start`)
59
+
> 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.
58
60
59
61
> Tests are written using [Jest](https://jestjs.io/)
60
62
61
-
#### 4. Create a branch and commit
63
+
## Project branch strategy
64
+
65
+
This project's branch strategy is based on the [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). To summarize:
66
+
67
+
- Every feature should be developed in its own branch.
68
+
- Completed features should be merged into the `dev` branch, which represents the bleeding edge of stable development.
69
+
- While a release is in testing, a short-lived `release-X.Y.Z` branch is created to isolate fixes from new feature development.
70
+
- When a release is completed, the `release-X.Y.Z` branch is merged into `dev` and the corresponding `release-X.Y` branch, then the `dev` branch is merged into the `main` branch, which represents the most recent stable release of the project.
71
+
- Long-lived `release-X.Y` branches are retained to allow backporting of fixes.
72
+
73
+
See the release process below for more details.
74
+
75
+
Please target the `dev` branch when opening pull requests against the project, except when contributing a bug fix to an active `release-X.Y.Z` branch.
76
+
77
+
### Creating a branch and committing
78
+
79
+
After making your changes to the code in the dev branch, you can...
62
80
63
81
```bash
64
82
# Create a git branch
65
-
git checkout -b my-improvement
83
+
git checkout -b feature/my-improvement
66
84
67
85
# Add changes
68
86
git add .
@@ -71,29 +89,40 @@ git add .
71
89
git commit -m "fix(component): message"
72
90
```
73
91
74
-
#### 5. Create a release
92
+
After pushing your new branch to your fork, you can create a PR; see: https://guides.github.com/activities/forking/
75
93
76
-
<!-- ```bash
77
-
git commit -m "Release v1.2.3"
78
-
git tag v1.2.3
79
-
git push origin main v1.2.3
80
-
``` -->
94
+
## Creating a release
81
95
82
-
Checkout the `main` branch, and ensure it is up-to-date.
96
+
### Pre-Release Planning
83
97
84
-
Run `npm version [major | minor | patch]` for example:
98
+
Before a release can be made, some planning is required:
85
99
86
-
```bash
87
-
npm version patch
88
-
```
100
+
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.
101
+
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).
102
+
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 candidate process can begin immediately.
89
103
90
-
This will update the `package.json` version and create a git tag. Then push both the main/tag.
104
+
### Release Candidate Process
91
105
92
-
```bash
93
-
git push origin main v0.0.8
94
-
```
106
+
A series of Release Candidates should be created and tested to ensure that the final release is stable. Note that the examples in the steps below assume that Git is set up with an `upstream` remote pointing at the main Universal Viewer repository and an `origin` remote pointing at the Release Manager's fork. Replace X.Y.Z in all steps with the version determined in step 2 of Pre-Release Planning.
107
+
108
+
1. When it's time to begin the release process, the Release Manager will create a `release-X.Y.Z` branch off of `dev`: `git checkout dev ; git checkout -b release-X.Y.Z ; git push --set-upstream upstream release-X.Y.Z`
109
+
2. The Release Manager should next create a pull request against the new branch containing the result of using NPM to bump the version: `git checkout -b release-X.Y.Z-rc1 ; npm version X.Y.Z-rc1 ; git push --set-upstream origin release-X.Y.Z-rc1`. When creating the PR on GitHub, be sure that you target the appropriate release branch, not `dev`. This PR can be merged immediately; its purpose is to create an easily accessible public preview and a public forum for discussion of the RC. The description of this pull request should highlight major changes and areas where testing is needed; you can use the GitHub compare tool to review commits -- e.g. `https://github.com/UniversalViewer/universalviewer/compare/main...release-X.Y.Z` will show all commits added between the last stable release and the new release-in-progress.
110
+
3. The release tag created during step 2 should be pushed to the main GitHub repository to trigger publishing of the release candidate to NPM: `git push upstream vX.Y.Z-rc1`
111
+
4. Next, the Steering Group will announce the release candidate 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.
112
+
5. 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 1-4 will be repeated with an incremented "rc" number (e.g. X.Y.Z-rc2) to ensure that no problems remain.
113
+
6. 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.
114
+
115
+
### Making a Normal Release
116
+
117
+
Once a stable release is ready to be published, these steps can be followed by the Release Manager:
118
+
119
+
1. On the `release-X.Y.Z` 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.
120
+
2. Merge the `release-X.Y.Z` branch into both `dev` and the matching `release-X.Y` branch. Create the `release-X.Y` branch if it does not already exist. The `release-X.Y` branch will be long-lived, used to create backported patch releases as needed; the `release-X.Y.Z` branch will be deleted as part of the release process, as it is no longer needed.
121
+
3. Merge the `release-X.Y` branch into the `main` branch, so that `main` continues to point to the most recent stable release.
122
+
4. All changed/deleted branches and newly-created release tags must be pushed to GitHub; e.g. `git push origin main dev v4.1.0 release-4.1 :release-4.1.0`. (Note the colon on `:release-4.1.0` -- this deletes the short-lived release branch while updating all of the long-lived branches).
123
+
5. At this point, a GitHub action will recognize the new version tag and publish the package to NPM.
124
+
6. Don't forget to create a release with appropriate release notes through the GitHub web interface to make the new version more visible.
95
125
96
-
Then the GitHub action will pick up the tag and publish it to NPM.
126
+
### Backporting a Bug Fix
97
127
98
-
Create a PR:
99
-
https://guides.github.com/activities/forking/
128
+
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.
0 commit comments