From 3fc195f907bd60ab65c5261c6059075e9f64113d Mon Sep 17 00:00:00 2001 From: Cary Phillips Date: Sun, 5 May 2019 12:50:03 -0700 Subject: [PATCH 01/10] Meeting notes 2019-5-2 --- aswf-tsc/meetings/2019-05-02.md | 59 +++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 aswf-tsc/meetings/2019-05-02.md diff --git a/aswf-tsc/meetings/2019-05-02.md b/aswf-tsc/meetings/2019-05-02.md new file mode 100644 index 0000000000..fd8ce7d53c --- /dev/null +++ b/aswf-tsc/meetings/2019-05-02.md @@ -0,0 +1,59 @@ +5/2/2019 +======== + +Attending: +* John Mertic +* Cary Phillips +* Rod Bogart +* Peter Hillman +* Larry Gritz +* Daniel Heckenberg + +Personal introductions: +----------------------- + +* John Mertic: Linux Foundation - Director of Program Management. Help getting project up and going, helping with issues and concerns. +* Peter Hillman: Weta, worked on OpenEXR deep stuff. +* Cary Phillips: ILM R&D Supervisor, miscellaneous contributions to IlmBase. +* Larry Gritz: Sony Pictures Imageworks, experience as a user of OpenEXR, lead for OpenImageIO (the major client of OpenEXR, sits between the library and most users). +* Rod Bogart: One of the originators with Florian Kainz and Drew Hess. Involvement has been on and off, mostly off lately. Vice chair of the Academy’s ACES project. +* Daniel Heckenberg: ASWF TAC chair. + +Discussion: +----------- + +* John: We are the Technical Steering Committee: +- Set direction, features, roadmap. +- Issues, questions, +- Serves the community, not necessarily an overlord. +- Has the help of the TAC + +* Need to set up a TSC subdirectory in the github repo, to hold meeting notes, etc. + +* There are three github repos: +- Openexr +- Openexr-website +- Openexr-images (big test images, nice to not pollute the main repo with them) + +* Other contributors: +- Kimball Thurston - Weta +- Nick Rasmussen - ILM +- Nick Porcino - Occulus, formerly ILM +- Jonathan Stone - Lucasfilm/MaterialX + +* ASWF member organization have obligation to contribute to projects. + +* Larry: OCIO has a separate role for TSC chair. We can be creative with how we divide the roles. Few things come to formal votes. + +* Cary elected TSC chair + +* Action items: +- Set up aswf.io mailing lists; send message asking recipients to sign up over there; this lets us know who the community is. +- Set up private TSC alias. +- Move github repo to ASWF (contents will be unchanged, address will not change) +- John: contact Steve Winslow about code scanning, make sure license compliance in order. +- Cary: Add permissions to github repos + + + + From 8187cde2926a7956f2cd26ad709be769c1cd014f Mon Sep 17 00:00:00 2001 From: Cary Phillips Date: Sun, 5 May 2019 12:57:59 -0700 Subject: [PATCH 02/10] formatting --- aswf-tsc/meetings/2019-05-02.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/aswf-tsc/meetings/2019-05-02.md b/aswf-tsc/meetings/2019-05-02.md index fd8ce7d53c..c5eb86781c 100644 --- a/aswf-tsc/meetings/2019-05-02.md +++ b/aswf-tsc/meetings/2019-05-02.md @@ -23,23 +23,24 @@ Discussion: ----------- * John: We are the Technical Steering Committee: -- Set direction, features, roadmap. -- Issues, questions, -- Serves the community, not necessarily an overlord. -- Has the help of the TAC + + * Set direction, features, roadmap. + * Issues, questions, + * Serves the community, not necessarily an overlord. + * Has the help of the TAC * Need to set up a TSC subdirectory in the github repo, to hold meeting notes, etc. * There are three github repos: -- Openexr -- Openexr-website -- Openexr-images (big test images, nice to not pollute the main repo with them) + - Openexr + - Openexr-website + - Openexr-images (big test images, nice to not pollute the main repo with them) * Other contributors: -- Kimball Thurston - Weta -- Nick Rasmussen - ILM -- Nick Porcino - Occulus, formerly ILM -- Jonathan Stone - Lucasfilm/MaterialX + - Kimball Thurston - Weta + - Nick Rasmussen - ILM + - Nick Porcino - Occulus, formerly ILM + - Jonathan Stone - Lucasfilm/MaterialX * ASWF member organization have obligation to contribute to projects. @@ -48,11 +49,11 @@ Discussion: * Cary elected TSC chair * Action items: -- Set up aswf.io mailing lists; send message asking recipients to sign up over there; this lets us know who the community is. -- Set up private TSC alias. -- Move github repo to ASWF (contents will be unchanged, address will not change) -- John: contact Steve Winslow about code scanning, make sure license compliance in order. -- Cary: Add permissions to github repos + - Set up aswf.io mailing lists; send message asking recipients to sign up over there; this lets us know who the community is. + - Set up private TSC alias. + - Move github repo to ASWF (contents will be unchanged, address will not change) + - John: contact Steve Winslow about code scanning, make sure license compliance in order. + - Cary: Add permissions to github repos From 22bbd4d4a8ffc01b1ea4bb26c77a6c8c34db5249 Mon Sep 17 00:00:00 2001 From: seabeepea Date: Sun, 9 Jun 2019 13:17:21 -0700 Subject: [PATCH 03/10] added GOVERNANCE.md --- GOVERNANCE.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 GOVERNANCE.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000000..77d300e540 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,155 @@ +# OpenEXR Project Governance + +The OpenEXR project is owned by the Academy Software Foundation and is governed by its Committers, including a Technical +Steering Committee (TSC) which is responsible for high-level guidance of the +project. + +## Contributors + +The OpenEXR project grows and thrives from assistance from Contributors. +Contributors include anyone in the community that contributes code, +documentation, or other technical artifacts that have been incorporated into the +projects repository. + +## Committers + +The OpenEXR GitHub repository is maintained by OpenEXR Committers. Committers +are Contributors who have earned the ability to modify source code, +documentation, or other technical artifacts to the project. Upon becoming +Committers, they become members of the OpenEXR leadership team. + +Their privileges include, but are not limited to: + +* Commit access to the OpenEXR repository +* Moderator status on all communication channels + +### Committer Activities + +Typical activities of a Committer include: + +* Helping users and novice contributors +* Ensuring a response to questions posted to the openexr-dev alias +* Contributing code and documentation changes that improve the project +* Reviewing and commenting on issues and pull requests +* Participation in working groups +* Merging pull requests + +The TSC periodically reviews the Committer list to identify inactive Committers. +Past Committers are typically given Emeritus status. Emeriti may request that +the TSC restore them to active Committer status. + +### Committer Nominations + +Any existing Committer can nominate an individual making significant and +valuable contributions to the OpenEXR project to become a new Committer. + +To nominate a new Committer, open an issue in the OpenEXR repository, with a +summary of the nominee's contributions. + +If there are no objections raised by any Committers two weeks after the issue is +opened, the nomination will be considered as accepted. Should there be any +objections against the nomination, the TSC is responsible for working with the +individuals involved and finding a resolution. The nomination must be approved +by the TSC, which is assumed when there are no objections from any TSC members. + +Prior to the public nomination, the Committer initiating it may seek feedback +from other Committers in private channels and work with the nominee to improve +the nominee's contribution profile, in order to make the nomination as +frictionless as possible. + +If individuals making valuable contributions do not believe they have been +considered for a nomination, they may log an issue or contact a Committer +directly. + +## Technical Steering Committee + +A subset of the Committers forms the Technical Steering Committee (TSC), which +has final authority over this project. As defined in the project charter, TSC +responsibilities include, but are not limited to: + +* Coordinating technical direction of the Project +* Project governance and process (including this policy) +* Contribution policy +* GitHub repository hosting +* Conduct guidelines +* Maintaining the list of additional Committers +* Appointing representatives to work with other open source or open standards +communities +* Discussions, seeking consensus, and where necessary, voting on technical +matters relating to the code base that affect multiple projects +* Coordinating any marketing, events, or communications regarding the project + +The TSC has a Chair, who acts as the project manager, organizing meetings and +providing oversight to project administration. The Chair is elected by the TSC. +The Chair also serves as the OpenEXR representative on the Academy Software Foundation (ASWF) Technical +Advisory Council (TAC). The chair represents the +project at all ASWF TAC meetings. + +### TSC Leaders + +* Chair: Cary Phillips + +### TSC Members + +* Cary Phillips - Industrial Light & Magic +* Rod Bogart - Epic Games +* Larry Gritz - Sony Pictures ImageWorks +* Peter Hillman - Weta Digital, Ltd. +* Kimball Thurston - Weta Digital, Ltd. +* Nick Porcino - Oculus +* Christina Templaar-Leitz - Epic Games +* John Mertic - The Linux Foundation + +### TSC Meetings + +The TSC meets each Thursday at 1pm Pacific Time via Zoom video conference. +TSC meetings are open to the public, https://zoom.us/j/8362240307. +The TSC Chair moderates the meeting, or appoints another TSC member to moderate in his or her absence. + +Items are added to the TSC agenda which are considered contentious or are +modifications of governance, contribution policy, TSC membership, or release +process, in addition to topics involving the high-level technical direction of +the project. + +The intention of the agenda is not to approve or review all patches. That should +happen continuously on GitHub and be handled by the larger group of Committers. + +Any community member or Contributor can ask that something be reviewed by the +TSC at the meeting by logging a GitHub issue. Any Committer, TSC member, or the meeting chair +can bring the issue to the TSC's attention by applying the `tsc-review` label. + +Prior to each TSC meeting, the meeting chair will share the agenda with members +of the TSC. TSC members can also add items to the agenda at the beginning of +each meeting. The meeting chair and the TSC cannot veto or remove items. + +The TSC may invite additional persons to participate in a non-voting capacity. + +The meeting chair is responsible for archiving the minutes, stored at +https://github.com/openexr/openexr/tree/master/aswf-tsc/meetings. + +Due to the challenges of scheduling a global meeting with participants in +several time zones, the TSC will seek to resolve as many agenda items as +possible outside of meetings on the public mailing list. + +### TSC Nomination + +Any proposal for additional members of the TSC may be submitted by Committers +and/or TSC members by opening an issue outlining their case. Formal consensus +should be reached by the existing TSC members. No objections raised by any TSC +members two weeks after the issue is opened does not imply acceptance, if +general consensus cannot be reached by this time a formal vote is required. + +Should there be any objections against the nomination, the TSC is responsible +for working with the individuals involved and finding a resolution. + +### TSC Succession + +A voting member of the TSC may nominate a successor in the event that such +voting member decides to leave the TSC, and the TSC, including the departing +member, shall confirm or reject such nomination by a vote. + +In the event that the departing member’s nomination for successor is rejected by +vote of the TSC, the departing member shall be entitled to continue nominating +successors until one such successor is confirmed by vote of the TSC. If the +departing member fails or is unable to nominate a successor, the TSC may +nominate one on the departing member’s behalf. From b72609cef73f4f932f1d4096d41e161d6e99bc4b Mon Sep 17 00:00:00 2001 From: seabeepea Date: Sun, 9 Jun 2019 16:14:29 -0700 Subject: [PATCH 04/10] CONTRIBUTING.md, INSTALL.md, and changes README.md and INSTALL.md --- CONTRIBUTING.md | 377 ++++++++++++++++++++++++++++++++++++++++++++++++ GOVERNANCE.md | 26 ++-- INSTALL.md | 105 ++++++++++++++ README.md | 118 +-------------- 4 files changed, 506 insertions(+), 120 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 INSTALL.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..933e850a29 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,377 @@ +# Contributing to OpenEXR + +Thank you for your interest in contributing to OpenEXR. This document +explains our contribution process and procedures, so please review it first. + +## Getting Connected + +There are two primary ways to connect with the OpenEXR project: + +* The [openexr-dev](https://lists.aswf.io/g/openexr-dev) mail list: +This is a development focused mail list with a deep history of technical +conversations and decisions that have shaped the project. + +* [GitHub Issues](https://github.com/openexr/openexr/issues): GitHub +**issues** are a great place to start a conversation! Issues aren’t +just for bugs, they are also for feature requests and other +suggestions, for the code or documentation or the website. The only +conversations not appropriate for issues are questions in the form of +“How do I do X”. Please direct these to the openexr-dev mail lists, +and consider contributing what you've learned to our docs if +appropriate. + +## Bug Reports and Issue Tracking + +OpenEXR use GitHub's issue tracking system for bugs and enhancements: +https://github.com/openexr/openexr/issues + +**If you are merely asking a question ("how do I...")**, please do not file +an issue, but instead ask the question on the +[openexr-dev](http://lists.aswf.io/openexr-dev) mailing list. + +If you are submitting a bug report, please be sure to note which +version of OpenEXR you are using, on what platform (OS/version, which +compiler you used, and any special build flags or other unusual +environmental issues). Please give a specific an account of + +* what you tried +* what happened +* what you expected to happen instead + +with enough detail that others can reproduce the problem. + +## Reporting Vulnerabilities + +If you think you've found a potential vulnerability in OpenEXR, please +report it by emailing security@openexr.com. Only TSC members and ASWF +project management have access to these messages. Include detailed +steps to reproduce the issue, and any other information that could aid +an investigation. + +## Git Basics + +Working with OpenEXR requires understanding a significant amount of +Git and GitHub based terminology. If you’re unfamiliar with these +tools or their lingo, please look at the [GitHub +Glossary](https://help.github.com/articles/github-glossary/) or browse +[GitHub Help](https://help.github.com/). + +To contribute, you need a GitHub account. This is needed in order to +push changes to the upstream repository. After setting up your account +you should then **fork** the OpenEXR repository to your account. This +creates a copy of the repository under your user namespace and serves +as the “home base” for your development branches, from which you will +submit **pull requests** to the upstream repository to be merged. + +You will also need Git installed on your local development machine. If +you need setup assistance, please see the official [Git +Documentation](https://git-scm.com/doc). + +Once your Git environment is operational, the next step is to locally +**clone** your forked OpenColorIO repository, and add a **remote** +pointing to the upstream OpenColorIO repository. These topics are +covered in [Cloning a repository] +(https://help.github.com/articles/cloning-a-repository/) and +[Configuring a remote for a fork] +(https://help.github.com/articles/configuring-a-remote-for-a-fork/), +but again, if you need assistance feel free to reach out on the +openexr-dev mail list. + +## Contributor Licence Agreements + +Developers who wish to contribute code to be considered for inclusion +in the OpenEXR distribution must first complete a **Contributor +License Agreement**. + +Trivial changes (such as an alteration to the Makefiles, a one-line +bug fix, etc.) may be accepted without a CLA, at the sole discretion of the +project leader, but anything complex requires a CLA. + +* If you are an individual writing the code on your own time and +you're SURE you are the sole owner of any intellectual property you +contribute, use the [Individual Contributor License Agreement] +(http://www.openexr.com/downloads/OpenEXRIndividualContributorLicenseAgreement.docx). + +* If you are writing the code as part of your job, or if there is any +possibility that your employers might think they own any intellectual +property you create, then you should use the [Corporate Contributor +Licence Agreement] +(http://www.openexr.com/downloads/OpenEXRCorporateContributorLicenseAgreement.docx). + +Download the appropriate CLA from the links above (or find them in the +src/doc directory of the software distribution), print, sign, and +rescan it (or just add a digital signature directly), and email it +back to us (info@openexr.com). + +The OpenEXR CLA's are the standard forms used by Linux Foundation +projects. + +### Commit Sign-Off + +Every commit must be signed off. That is, every commit log message +must include a “`Signed-off-by`” line (generated, for example, with +“`git commit --signoff`”), indicating that the committer wrote the +code and has the right to release it under the [MPL +2.0](https://www.mozilla.org/MPL/2.0/) license. See +http://developercertificate.org/ for more information on this +requirement. + +## Repository Structure and Commit Policy + +The OpenEXR repository uses a simple branching and merging strategy. + +All development work is done directly on the master branch. The master +branch represents the bleeding-edge of the project and any +contributions should be done on top of it. + +After sufficient work is done on the master branch and the OpenEXR +leadership determines that a release is due, we will bump the relevant +internal versioning and tag a commit with the corresponding version +number, e.g. v2.0.1. Each Minor version also has its own “Release +Branch”, e.g. RB-1.1. This marks a branch of code dedicated to that +Major.Minor version, which allows upstream bug fixes to be +cherry-picked to a given version while still allowing the master +branch to continue forward onto higher versions. This basic repository +structure keeps maintenance low, while remaining simple to understand. + +To reiterate, the master branch represents the latest development +version, so beware that it may include untested features and is not +generally stable enough for release. To retrieve a stable version of +the source code, use one of the release branches. + +This development workflow is sometimes referred to as +[OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow). It +leads to a simple, clean, linear edit history in the repo. + +## Development and Pull Requests + +Contributions should be submitted as Github pull requests. See +[Creating a pull request](https://help.github.com/articles/creating-a-pull-request/) +if you're unfamiliar with this concept. + +The development cycle for a code change should follow this protocol: + +1. Create a topic branch in your local repository, following the naming format +"feature/" or "bugfix/". + +2. Make changes, compile, and test thoroughly. Code style should match existing +style and conventions, and changes should be focused on the topic the pull +request will be addressing. Make unrelated changes in a separate topic branch +with a separate pull request. + +3. Push commits to your fork. + +4. Create a Github pull request from your topic branch. + +5. All pull requests trigger CI builds on [Travis CI](https://travis-ci.org/) +for Linux and Mac OS and [AppVeyor](https://www.appveyor.com/) for Windows. +These builds verify that code compiles and all unit tests succeed. CI build +status is displayed on the GitHub PR page, and changes will only be considered +for merging after all builds have succeeded. + +6. Pull requests will be reviewed by project Committers and Contributors, +who may discuss, offer constructive feedback, request changes, or approve +the work. + +7. Upon receiving the required number of Committer approvals (as outlined +in [Required Approvals](#required-approvals)), a Committer other than the PR +contributor may squash and merge changes into the master branch. + +See also (from the OpenEXR Developer Guide): +* [Getting started](http://opencolorio.org/developers/getting_started.html) +* [Submitting Changes](http://opencolorio.org/developers/submitting_changes.html) + +## Code Review and Required Approvals + +Modifications of the contents of the OpenEXR repository are made on a +collaborative basis. Anyone with a GitHub account may propose a +modification via pull request and it will be considered by the project +Committers. + +Pull requests must meet a minimum number of Committer approvals prior +to being merged. Rather than having a hard rule for all PRs, the +requirement is based on the complexity and risk of the proposed +changes, factoring in the length of time the PR has been open to +discussion. The following guidelines outline the project's established +approval rules for merging: + +* Core design decisions, large new features, or anything that might be +perceived as changing the overall direction of the project should be +discussed at length in the mail list before any PR is submitted, in +order to: solicit feedback, try to get as much consensus as possible, +and alert all the stakeholders to be on the lookout for the eventual +PR when it appears. + +* Small changes (bug fixes, docs, tests, cleanups) can be approved and +merged by a single Committer. + +* Big changes that can alter behavior, add major features, or present +a high degree of risk should be signed off by TWO Committers, ideally +one of whom should be the "owner" for that section of the codebase (if +a specific owner has been designated). If the person submitting the PR +is him/herself the "owner" of that section of the codebase, then only +one additional Committer approval is sufficient. But in either case, a +48 hour minimum is helpful to give everybody a chance to see it, +unless it's a critical emergency fix (which would probably put it in +the previous "small fix" category, rather than a "big feature"). + +* Escape valve: big changes can nonetheless be merged by a single +Committer if the PR has been open for over two weeks without any +unaddressed objections from other Committers. At some point, we have +to assume that the people who know and care are monitoring the PRs and +that an extended period without objections is really assent. + +Approval must be from Committers who are not authors of the change. If +one or more Committers oppose a proposed change, then the change +cannot be accepted unless: + +* Discussions and/or additional changes result in no Committers +objecting to the change. Previously-objecting Committers do not +necessarily have to sign-off on the change, but they should not be +opposed to it. + +* The change is escalated to the TSC and the TSC votes to approve the +change. This should only happen if disagreements between Committers +cannot be resolved through discussion. + +Committers may opt to elevate significant or controversial +modifications to the TSC by assigning the `tsc-review` label to a pull +request or issue. The TSC should serve as the final arbiter where +required. + +## Coding Style + +#### Formatting + +We use [clang-format](https://clang.llvm.org/docs/ClangFormat.html) +to uniformly format our source code prior to PR submission. Make sure that +clang-format is installed on your local machine, and just run + + make clang-format + +and it will automatically reformat your code according to the configuration +file found in the `.clang-format` file at the root directory of the OpenEXR +source code checkout. + +One of the TravisCI test matrix entries runs clang-format and fails if any +diffs were generated (that is, if any of your code did not 100% conform to +the `.clang-format` formatting configuration). If it fails, clicking on that +test log will show you the diffs generated, so that you can easily correct +it on your end and update the PR with the formatting fixes. + +If you don't have clang-format set up on your machine, and your patch is not +very long, you may find that it's more convenient to just submit it and hope +for the best, and if it doesn't pass the Travis test, look at the diffs in +the log and make the corrections by hand and then submit an update to the +patch (i.e. relying on Travis to run clang-format for you). + +Because the basic formatting is automated by clang-format, we won't +enumerate the rules here. + +#### File conventions + +C++ implementation should be named `*.cpp`. Headers should be named `.h`. +All headers should contain + + #pragma once + +All source files should begin with the copyright and license, which +can be found in the [LICENSE](LICENSE.md) file (or cut and pasted from +any other other source file). + +For NEW source files, please change the copyright year to the present. DO +NOT edit existing files only to update the copyright year, it just creates +pointless deltas and offers no increased protection. + + +#### Identifiers + +In general, classes and templates should start with upper case and +capitalize new words: `class CustomerList;` In general, local variables +should start with lower case. Macros should be `ALL_CAPS`, if used at all. + +If your class is extremely similar to, or modeled after, something in the +standard library, Boost, or something else we interoperate with, it's ok to +use their naming conventions. For example, very general utility classes and +templates (the kind of thing you would normally find in std or boost) should +be lower case with underscores separating words, as they would be if they +were standards. + + template shared_ptr; + class scoped_mutex; + +Names of data should generally be nouns. Functions/methods are trickier: a +the name of a function that returns a value but has no side effects should +be a noun, but a procedure that performs an action should be a verb. + +#### Class structure + +Try to avoid public data members, although there are some classes that serve +a role similar to a simple C struct -- a very straightforward collection of +data members. In these, it's fine to make the data members public and have +clients set and get them directly. + +Private member data should be named m_foo (alternately, it's ok to use the +common practice of member data foo_, but don't mix the conventions within a +class). + +Private member data that needs public accessors should use the convention: + + void foo (const T& newfoo) { m_foo = newfoo; } + const T& foo () const { return m_foo; } + +Avoid multiple inheritance. + +Namespaces: yes, use them! + +#### Third-party libraries + +Prefer C++11 `std` rather than Boost, where both can do the same task. +Feel free to use Boost classes you already see in the code base, but don't +use any Boost you don't see us already using, without first checking with +the project leader. + +#### Comments and Doxygen + +Comment philosophy: try to be clear, try to help teach the reader what's +going on in your code. + +Prefer C++ comments (starting line with `//`) rather than C comments (`/* ... */`). + +For public APIs we tend to use Doxygen-style comments (start with `///`). +They looks like this: + + /// Explanation of a class. Note THREE slashes! + /// Also, you need at least two lines like this. If you don't have enough + /// for two lines, make one line blank like this: + /// + class myclass { + .... + float foo; ///< Doxygen comments on same line look like this + } + +#### Miscellaneous + +Macros should be used only rarely -- prefer inline functions, templates, +enums, or "const" values wherever possible. + +Prefer `std::unique_ptr` over raw new/delete. + +#### Bottom Line + +When in doubt, look elsewhere in the code base for examples of similar +structures and try to format your code in the same manner, or ask on +the openexr-dev mail list. + +For standards on contributing to documentation, see the [Documentation +Guidelines](http://opencolorio.org/developers/documentation_guidelines.html). + +## Versioning Policy + +OpenEXR uses [semantic versioning](https://semver.org), which labels +each version with three numbers: Major.Minor.Patch, where: + +* **MAJOR** indicates incompatible API changes, +* **MINOR** indicates functionality added in a backwards-compatible manner +* **PATCH** indicates backwards-compatible bug fixes + diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 77d300e540..7e4ed655f4 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,8 +1,8 @@ # OpenEXR Project Governance -The OpenEXR project is owned by the Academy Software Foundation and is governed by its Committers, including a Technical -Steering Committee (TSC) which is responsible for high-level guidance of the -project. +The OpenEXR project is owned by the Academy Software Foundation and is +governed by its Committers, including a Technical Steering Committee +(TSC) which is responsible for high-level guidance of the project. ## Contributors @@ -63,9 +63,12 @@ directly. ## Technical Steering Committee -A subset of the Committers forms the Technical Steering Committee (TSC), which -has final authority over this project. As defined in the project charter, TSC -responsibilities include, but are not limited to: +The Technical Steering Committee (TSC) oversees the overall technical +direction of OpenEXR, as defined in the project +[charter](aswf-tsc/charter/OpenEXR-Technical-Charter.md). This +charter defines the TSC member terms and succession policies. + +The responsibilities of the TSC include: * Coordinating technical direction of the Project * Project governance and process (including this policy) @@ -79,7 +82,7 @@ communities matters relating to the code base that affect multiple projects * Coordinating any marketing, events, or communications regarding the project -The TSC has a Chair, who acts as the project manager, organizing meetings and +The TSC elects a Chair person, who acts as the project manager, organizing meetings and providing oversight to project administration. The Chair is elected by the TSC. The Chair also serves as the OpenEXR representative on the Academy Software Foundation (ASWF) Technical Advisory Council (TAC). The chair represents the @@ -102,9 +105,12 @@ project at all ASWF TAC meetings. ### TSC Meetings -The TSC meets each Thursday at 1pm Pacific Time via Zoom video conference. -TSC meetings are open to the public, https://zoom.us/j/8362240307. -The TSC Chair moderates the meeting, or appoints another TSC member to moderate in his or her absence. +All meetings of the TSC are open to participation by any member of the +OpenEXR community. Meeting times are listed in the [ASWF technical +community calendar](https://lists.aswf.io/g/tac/calendar), currently +each Thursday at 1pm Pacific Time via Zoom video conference. The TSC +Chair moderates the meeting, or appoints another TSC member to +moderate in his or her absence. Items are added to the TSC agenda which are considered contentious or are modifications of governance, contribution policy, TSC membership, or release diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000000..a1bd11aebb --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,105 @@ +# Building and Installation + +Download the latest release of OpenEXR from +http://www.openexr.com/downloads.html. + +To build the OpenEXR binaries from source, compile and install the +individual sub-models (IlmBase, PyIlmBase, OpenEXR, OpenEXR_Viewers), +according to the instructions in the respective ``README`` +files. Build and install the IlmBase module first, then build and +install the OpenEXR module. Optionally, then build and install +PyIlmBase, OpenEXR_Viewers, and Contrib. + +For the basic installation: + + cd /IlmBase + ./configure + make + make install + + cd /OpenEXR + ./configure + make + make install + +See the module ``README`` files for options to ``configure``. + +## Building from Git + +Alternatively, you can download the latest release or the lastest +development branch directly from http://github.com/openexr. + +After cloning the repo locally, generate the configuration scripts by +running the ``bootstrap`` script: + + cd /IlmBase + ./bootstrap + ./configure + make + make install + + cd /OpenExr + ./bootstrap + ./configure + make + make install + +Building from git and ``bootstrap`` requires that **autoconf** is +installed. Download and install it from +https://www.gnu.org/software/autoconf/autoconf.html. + +## Building with CMake + +Alternatively, you can build with **cmake**, version 3.11 or newer. + +In the root ``CMakeLists.txt`` file, with -D options on the cmake +line, or by using a tools such as **ccmake** or **cmake-gui**, +configure the OpenEXR build. The options are detailed below. + +Create a source root directory, cd into it, and run **cmake** to configure +the build. Select an appropriate generator, such as "Unix Makefiles", +or "Visual Studio 15 2017 Win64". Then run **make** a the root +directory; this will build the appropriate submodules, according to +the settings of the **cmake** options, described below. + + cmake -DCMAKE_INSTALL_PREFIX= -G "selected generator" -DCMAKE_PREFIX_PATH= + make + +The available options are: + +* ``OPENEXR_BUILD_ILMBASE`` (ON) +By default, IlmBase is always built. + +* ``OPENEXR_BUILD_OPENEXR`` (ON) +By default, OpenEXR is always built. + +* ``OPENEXR_BUILD_PYTHON_LIBS`` (ON) +By default, the Python bindings will be built. + +* ``OPENEXR_BUILD_VIEWERS`` (OFF) +By default, the viewers are not built, as they have not been updated for +modern OpenGL. + +* ``OPENEXR_BUILD_SHARED`` (ON) +* ``OPENEXR_BUILD_STATIC`` (OFF) +The build can be configured to create either shared libraries, or static +libraries, or both. + +* ``OPENEXR_NAMESPACE_VERSIONING`` (ON) +OpenEXR symbols will be contained within a namespace + +* ``OPENEXR_FORCE_CXX03`` (OFF) +C++03 compatibility is possible as an option + +* ``OPENEXR_ENABLE_TESTS`` (ON) +By default, the tests will be built. + +* ``OPENEXR_RUN_FUZZ_TESTS`` (OFF) +By default, the damaged input tests will NOT be run, due to their long +running time. If you wish to run them as part of "make test" (or equivalent +in your build system), then enable this. A "make fuzz" target will be +available to run the fuzz test regardless. + +* ``OPENEXR_PYTHON_MAJOR``, ``OPENEXR_PYTHON_MINOR`` "2", "7" +By default, OpenEXR is built against Python 2.7.x. + diff --git a/README.md b/README.md index 92b15d01fa..1c144b2104 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,8 @@ License ------- OpenEXR, including all contributions, is released under a modified BSD -license. Please see the ``LICENSE`` file accompanying the distribution -for the legal fine print. +license. Please see the [LICENSE.md] (LICENSE.md) file accompanying +the distribution for the legal fine print. OpenEXR Sub-modules ------------------- @@ -80,121 +80,19 @@ Web Resources Main web page: http:://www.openexr.org -GitHub repository: http://www.github.com/openexr +GitHub repository: http://www.github.com/openexr/openexr -Mail lists: +Mail list: -* **http://lists.nongnu.org/mailman/listinfo/openexr-announce** - OpenEXR-related announcements. - -* **http://lists.nongnu.org/mailman/listinfo/openexr-user** - for discussion about OpenEXR applications or general questions. - -* **http://lists.nongnu.org/mailman/listinfo/openexr-devel** - for developers using OpenEXR in their applications. +* [openexr-dev@lists.aswf.io] (https://lists.aswf.io/g/openexr-dev) Building and Installation ------------------------- -Download the latest release of OpenEXR from -http://www.openexr.com/downloads.html. - -To build the OpenEXR binaries from source, compile and install the -individual sub-models (IlmBase, PyIlmBase, OpenEXR, OpenEXR_Viewers), -according to the instructions in the respective ``README`` -files. Build and install the IlmBase module first, then build and -install the OpenEXR module. Optionally, then build and install -PyIlmBase, OpenEXR_Viewers, and Contrib. - -For the basic installation: - - cd /IlmBase - ./configure - make - make install - - cd /OpenEXR - ./configure - make - make install - -See the module ``README`` files for options to ``configure``. - -#### Building from Git - -Alternatively, you can download the latest release or the lastest -development branch directly from http://github.com/openexr. - -After cloning the repo locally, generate the configuration scripts by -running the ``bootstrap`` script: - - cd /IlmBase - ./bootstrap - ./configure - make - make install - - cd /OpenExr - ./bootstrap - ./configure - make - make install - -Building from git and ``bootstrap`` requires that **autoconf** is -installed. Download and install it from -https://www.gnu.org/software/autoconf/autoconf.html. - -#### Building with CMake - -Alternatively, you can build with **cmake**, version 3.11 or newer. - -In the root ``CMakeLists.txt`` file, with -D options on the cmake -line, or by using a tools such as **ccmake** or **cmake-gui**, -configure the OpenEXR build. The options are detailed below. - -Create a source root directory, cd into it, and run **cmake** to configure -the build. Select an appropriate generator, such as "Unix Makefiles", -or "Visual Studio 15 2017 Win64". Then run **make** a the root -directory; this will build the appropriate submodules, according to -the settings of the **cmake** options, described below. - - cmake -DCMAKE_INSTALL_PREFIX= -G "selected generator" -DCMAKE_PREFIX_PATH= - make - -The available options are: - -* ``OPENEXR_BUILD_ILMBASE`` (ON) -By default, IlmBase is always built. - -* ``OPENEXR_BUILD_OPENEXR`` (ON) -By default, OpenEXR is always built. - -* ``OPENEXR_BUILD_PYTHON_LIBS`` (ON) -By default, the Python bindings will be built. - -* ``OPENEXR_BUILD_VIEWERS`` (OFF) -By default, the viewers are not built, as they have not been updated for -modern OpenGL. - -* ``OPENEXR_BUILD_SHARED`` (ON) -* ``OPENEXR_BUILD_STATIC`` (OFF) -The build can be configured to create either shared libraries, or static -libraries, or both. - -* ``OPENEXR_NAMESPACE_VERSIONING`` (ON) -OpenEXR symbols will be contained within a namespace - -* ``OPENEXR_FORCE_CXX03`` (OFF) -C++03 compatibility is possible as an option - -* ``OPENEXR_ENABLE_TESTS`` (ON) -By default, the tests will be built. - -* ``OPENEXR_RUN_FUZZ_TESTS`` (OFF) -By default, the damaged input tests will NOT be run, due to their long -running time. If you wish to run them as part of "make test" (or equivalent -in your build system), then enable this. A "make fuzz" target will be -available to run the fuzz test regardless. +Download the latest release of OpenEXR from the GitHub Releases page: +[https://github.com/openexr/openexr/releases] (https://github.com/openexr/openexr/releases). -* ``OPENEXR_PYTHON_MAJOR``, ``OPENEXR_PYTHON_MINOR`` "2", "7" -By default, OpenEXR is built against Python 2.7.x. +For more information about building from sources, see the [INSTALL.md] (INSTALL.md) file. ## Documentation From fb6e8f44c3a1dd27fd52589fcab8b5b46ab2ee58 Mon Sep 17 00:00:00 2001 From: seabeepea Date: Sun, 9 Jun 2019 16:33:43 -0700 Subject: [PATCH 05/10] Contributing and Goverance sections --- README.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 1c144b2104..307d2374a7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -OpenEXR -======= +# OpenEXR **OpenEXR** is a high dynamic-range (HDR) image file format developed by Industrial Light & Magic (ILM) for use in computer imaging @@ -39,15 +38,13 @@ OpenEXR's features include: namespaces to provide protection when using multiple versions of the library in the same process space. -License -------- +## License OpenEXR, including all contributions, is released under a modified BSD license. Please see the [LICENSE.md] (LICENSE.md) file accompanying the distribution for the legal fine print. -OpenEXR Sub-modules -------------------- +## OpenEXR Sub-modules The OpenEXR distribution consists of the following sub-modules: @@ -62,8 +59,7 @@ Please see the ``README`` files of each of the individual directories for more i A collection of OpenEXR images is available from the adjacent repository [openexr-images](https://github.com/openexr/openexr-images). -Dependencies ------------- +## Dependencies OpenEXR depends on [zlib](https://zlib.net). @@ -75,25 +71,33 @@ In OpenEXR_Viewers: * **exrdisplay** depends on [fltk](http://www.fltk.org/index.php) * **playexr** depends on [Cg](https://developer.nvidia.com/cg-toolkit) -Web Resources -------------- +## Web Resources Main web page: http:://www.openexr.org GitHub repository: http://www.github.com/openexr/openexr -Mail list: +Deverloper discussion mailing list: * [openexr-dev@lists.aswf.io] (https://lists.aswf.io/g/openexr-dev) -Building and Installation -------------------------- +## Building and Installation Download the latest release of OpenEXR from the GitHub Releases page: -[https://github.com/openexr/openexr/releases] (https://github.com/openexr/openexr/releases). +https://github.com/openexr/openexr/releases. For more information about building from sources, see the [INSTALL.md] (INSTALL.md) file. +## Contributing + +See [CONTRIBUTING.md] (CONTRIBUTING.md) for more information about contributing to OpenEXR. + +## Project Goverance + +OpenEXR is owned by the Academy Software Foundation, and is maintained +by the developer community. See [GOVERNANCE.md] (GOVERNANCE.md) for +more infomation. + ## Documentation Documentation is available at http://www.openexr.com/documentation.html. From 0dfd328a9b462f6d14ed1c2e63e7abaaa375bda6 Mon Sep 17 00:00:00 2001 From: seabeepea Date: Sun, 9 Jun 2019 16:40:08 -0700 Subject: [PATCH 06/10] typos --- CONTRIBUTING.md | 14 +++++--------- README.md | 10 +++++----- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 933e850a29..645a679b09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,12 +70,10 @@ Documentation](https://git-scm.com/doc). Once your Git environment is operational, the next step is to locally **clone** your forked OpenColorIO repository, and add a **remote** pointing to the upstream OpenColorIO repository. These topics are -covered in [Cloning a repository] -(https://help.github.com/articles/cloning-a-repository/) and -[Configuring a remote for a fork] -(https://help.github.com/articles/configuring-a-remote-for-a-fork/), +covered in [Cloning a repository](https://help.github.com/articles/cloning-a-repository/) and +[Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/), but again, if you need assistance feel free to reach out on the -openexr-dev mail list. +openexr-dev@lists.aswf.io mail list. ## Contributor Licence Agreements @@ -89,14 +87,12 @@ project leader, but anything complex requires a CLA. * If you are an individual writing the code on your own time and you're SURE you are the sole owner of any intellectual property you -contribute, use the [Individual Contributor License Agreement] -(http://www.openexr.com/downloads/OpenEXRIndividualContributorLicenseAgreement.docx). +contribute, use the [Individual Contributor License Agreement](http://www.openexr.com/downloads/OpenEXRIndividualContributorLicenseAgreement.docx). * If you are writing the code as part of your job, or if there is any possibility that your employers might think they own any intellectual property you create, then you should use the [Corporate Contributor -Licence Agreement] -(http://www.openexr.com/downloads/OpenEXRCorporateContributorLicenseAgreement.docx). +Licence Agreement](http://www.openexr.com/downloads/OpenEXRCorporateContributorLicenseAgreement.docx). Download the appropriate CLA from the links above (or find them in the src/doc directory of the software distribution), print, sign, and diff --git a/README.md b/README.md index 307d2374a7..ebaf7b88bc 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ OpenEXR's features include: ## License OpenEXR, including all contributions, is released under a modified BSD -license. Please see the [LICENSE.md] (LICENSE.md) file accompanying +license. Please see the [LICENSE.md](LICENSE.md) file accompanying the distribution for the legal fine print. ## OpenEXR Sub-modules @@ -79,23 +79,23 @@ GitHub repository: http://www.github.com/openexr/openexr Deverloper discussion mailing list: -* [openexr-dev@lists.aswf.io] (https://lists.aswf.io/g/openexr-dev) +* [openexr-dev@lists.aswf.io](https://lists.aswf.io/g/openexr-dev) ## Building and Installation Download the latest release of OpenEXR from the GitHub Releases page: https://github.com/openexr/openexr/releases. -For more information about building from sources, see the [INSTALL.md] (INSTALL.md) file. +For more information about building from sources, see the [INSTALL.md](INSTALL.md) file. ## Contributing -See [CONTRIBUTING.md] (CONTRIBUTING.md) for more information about contributing to OpenEXR. +See [CONTRIBUTING.md](CONTRIBUTING.md) for more information about contributing to OpenEXR. ## Project Goverance OpenEXR is owned by the Academy Software Foundation, and is maintained -by the developer community. See [GOVERNANCE.md] (GOVERNANCE.md) for +by the developer community. See [GOVERNANCE.md](GOVERNANCE.md) for more infomation. ## Documentation From 3910ce7f66838f13e41c9d3427ddf8beceb9001b Mon Sep 17 00:00:00 2001 From: Cary Phillips Date: Tue, 11 Jun 2019 18:01:15 -0700 Subject: [PATCH 07/10] Edits to README.md and CONTRIBUTING.md --- CONTRIBUTING.md | 128 +++++++++++++++++++++++++++++++----------------- README.md | 68 ++++++++++++++++++------- 2 files changed, 133 insertions(+), 63 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 645a679b09..c6281d25e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,28 @@ # Contributing to OpenEXR Thank you for your interest in contributing to OpenEXR. This document -explains our contribution process and procedures, so please review it first. +explains our contribution process and procedures -## Getting Connected +## Getting Information There are two primary ways to connect with the OpenEXR project: * The [openexr-dev](https://lists.aswf.io/g/openexr-dev) mail list: -This is a development focused mail list with a deep history of technical -conversations and decisions that have shaped the project. +This is a development focused mail list with a deep history of +technical conversations and decisions that have shaped the project. * [GitHub Issues](https://github.com/openexr/openexr/issues): GitHub -**issues** are a great place to start a conversation! Issues aren’t -just for bugs, they are also for feature requests and other -suggestions, for the code or documentation or the website. The only -conversations not appropriate for issues are questions in the form of -“How do I do X”. Please direct these to the openexr-dev mail lists, -and consider contributing what you've learned to our docs if -appropriate. +**issues** are used both to track bugs and to discuss feature requests. -## Bug Reports and Issue Tracking +### How to Ask for Help + +If you have trouble installing, building, or using the library, but there's not yet reason to suspect you've encountered a genuine but, start by posting a question to the [openexr-dev](http://lists.aswf.io/openexr-dev) mailing list. This is the place for question such has "How do I...". + +### How to Report a Bug OpenEXR use GitHub's issue tracking system for bugs and enhancements: https://github.com/openexr/openexr/issues -**If you are merely asking a question ("how do I...")**, please do not file -an issue, but instead ask the question on the -[openexr-dev](http://lists.aswf.io/openexr-dev) mailing list. - If you are submitting a bug report, please be sure to note which version of OpenEXR you are using, on what platform (OS/version, which compiler you used, and any special build flags or other unusual @@ -40,7 +34,15 @@ environmental issues). Please give a specific an account of with enough detail that others can reproduce the problem. -## Reporting Vulnerabilities +### How to Request a Change + +Open a GitHub issue: https://github.com/openexr/openexr/issues. + +Describe the situation and the objective in as much detail as +possible. Feature requests will almost certainly spawn a discussion +among the project community. + +### How to Report a Security Vulnerability If you think you've found a potential vulnerability in OpenEXR, please report it by emailing security@openexr.com. Only TSC members and ASWF @@ -48,34 +50,23 @@ project management have access to these messages. Include detailed steps to reproduce the issue, and any other information that could aid an investigation. -## Git Basics +### How to Contribute a Bug Fix or Change -Working with OpenEXR requires understanding a significant amount of -Git and GitHub based terminology. If you’re unfamiliar with these -tools or their lingo, please look at the [GitHub -Glossary](https://help.github.com/articles/github-glossary/) or browse -[GitHub Help](https://help.github.com/). +To contribute code to the project, you'll need: -To contribute, you need a GitHub account. This is needed in order to -push changes to the upstream repository. After setting up your account -you should then **fork** the OpenEXR repository to your account. This -creates a copy of the repository under your user namespace and serves -as the “home base” for your development branches, from which you will -submit **pull requests** to the upstream repository to be merged. +* A good knowledge of git. +* A fork of the GitHub repo. +* An understanding of the project's development workflow +* Legal Authorization -You will also need Git installed on your local development machine. If -you need setup assistance, please see the official [Git -Documentation](https://git-scm.com/doc). +See below for details. -Once your Git environment is operational, the next step is to locally -**clone** your forked OpenColorIO repository, and add a **remote** -pointing to the upstream OpenColorIO repository. These topics are -covered in [Cloning a repository](https://help.github.com/articles/cloning-a-repository/) and -[Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/), -but again, if you need assistance feel free to reach out on the -openexr-dev@lists.aswf.io mail list. +## Legal Requirements + +OpenEXR is owned by the Academy Software Foundation and follows the +open source software best practice policies of the Linux Foundation. -## Contributor Licence Agreements +### Contributor Licence Agreements Developers who wish to contribute code to be considered for inclusion in the OpenEXR distribution must first complete a **Contributor @@ -97,7 +88,7 @@ Licence Agreement](http://www.openexr.com/downloads/OpenEXRCorporateContributorL Download the appropriate CLA from the links above (or find them in the src/doc directory of the software distribution), print, sign, and rescan it (or just add a digital signature directly), and email it -back to us (info@openexr.com). +back to us at [info@openexr.com](info@openexr.com). The OpenEXR CLA's are the standard forms used by Linux Foundation projects. @@ -112,12 +103,29 @@ code and has the right to release it under the [MPL http://developercertificate.org/ for more information on this requirement. -## Repository Structure and Commit Policy +## Development Workflow + +### Git Basics + +Working with OpenEXR requires understanding a significant amount of +Git and GitHub based terminology. If you’re unfamiliar with these +tools or their lingo, please look at the [GitHub +Glossary](https://help.github.com/articles/github-glossary/) or browse +[GitHub Help](https://help.github.com/). + +To contribute, you need a GitHub account. This is needed in order to +push changes to the upstream repository, via a pull request. + +You will also need Git installed on your local development machine. If +you need setup assistance, please see the official [Git +Documentation](https://git-scm.com/doc). + +### Repository Structure and Commit Policy The OpenEXR repository uses a simple branching and merging strategy. All development work is done directly on the master branch. The master -branch represents the bleeding-edge of the project and any +branch represents the bleeding-edge of the project and most contributions should be done on top of it. After sufficient work is done on the master branch and the OpenEXR @@ -135,11 +143,37 @@ version, so beware that it may include untested features and is not generally stable enough for release. To retrieve a stable version of the source code, use one of the release branches. +### The Git Workflow + This development workflow is sometimes referred to as [OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow). It leads to a simple, clean, linear edit history in the repo. -## Development and Pull Requests +The OpenEXR GitHub repo allows rebase merging and disallows merge +commits and squash merging. This ensures that the repo edit history +remains linear, avoiding the "bubbles" characteristic of the +[GitFlow](https://www.endoflineblog.com/gitflow-considered-harmful) +workflow. + +### Use the Fork, Luke. + +In a typical workflow, yous should **fork** the OpenEXR repository to +your account. This creates a copy of the repository under your user +namespace and serves as the “home base” for your development branches, +from which you will submit **pull requests** to the upstream +repository to be merged. + +Once your Git environment is operational, the next step is to locally +**clone** your forked OpenColorIO repository, and add a **remote** +pointing to the upstream OpenColorIO repository. These topics are +covered in [Cloning a +repository](https://help.github.com/articles/cloning-a-repository/) +and [Configuring a remote for a +fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/), +but again, if you need assistance feel free to reach out on the +openexr-dev@lists.aswf.io mail list. + +### Pull Requests Contributions should be submitted as Github pull requests. See [Creating a pull request](https://help.github.com/articles/creating-a-pull-request/) @@ -177,7 +211,7 @@ See also (from the OpenEXR Developer Guide): * [Getting started](http://opencolorio.org/developers/getting_started.html) * [Submitting Changes](http://opencolorio.org/developers/submitting_changes.html) -## Code Review and Required Approvals +### Code Review and Required Approvals Modifications of the contents of the OpenEXR repository are made on a collaborative basis. Anyone with a GitHub account may propose a @@ -362,7 +396,9 @@ the openexr-dev mail list. For standards on contributing to documentation, see the [Documentation Guidelines](http://opencolorio.org/developers/documentation_guidelines.html). -## Versioning Policy +## Release Management + +### Versioning Policy OpenEXR uses [semantic versioning](https://semver.org), which labels each version with three numbers: Major.Minor.Patch, where: diff --git a/README.md b/README.md index ebaf7b88bc..1400fd28f0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # OpenEXR +[![License](https://img.shields.io/badge/License-BSD%203%20Clause-blue.svg)](LICENSE.md) +[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2799/badge)](https://bestpractices.coreinfrastructure.org/projects/2799) + **OpenEXR** is a high dynamic-range (HDR) image file format developed by Industrial Light & Magic (ILM) for use in computer imaging applications. It supports stereoscopic and deep images. Weta Digital, @@ -38,12 +41,6 @@ OpenEXR's features include: namespaces to provide protection when using multiple versions of the library in the same process space. -## License - -OpenEXR, including all contributions, is released under a modified BSD -license. Please see the [LICENSE.md](LICENSE.md) file accompanying -the distribution for the legal fine print. - ## OpenEXR Sub-modules The OpenEXR distribution consists of the following sub-modules: @@ -54,11 +51,22 @@ The OpenEXR distribution consists of the following sub-modules: * **OpenEXR_Viewers** - Standard image viewing programs * **Contrib** - Various plugins and utilities, contributed by the community. -Please see the ``README`` files of each of the individual directories for more information. +Please see the README.md files of each of the individual directories for more information. A collection of OpenEXR images is available from the adjacent repository [openexr-images](https://github.com/openexr/openexr-images). +## Supported Platforms + +The OpenEXR codebase can be built with any of the following: + +* Linux: GCC 4.8 or newer +* Microsoft Visual Studio 2015 or newer +* Mac OS + +The Python bindings in PyIlmBase support Python 2.6 and 2.7; they have +not been tested for Python 3. + ## Dependencies OpenEXR depends on [zlib](https://zlib.net). @@ -73,30 +81,56 @@ In OpenEXR_Viewers: ## Web Resources -Main web page: http:://www.openexr.org +* Main web page: http:://www.openexr.org -GitHub repository: http://www.github.com/openexr/openexr +* GitHub repository: http://www.github.com/openexr/openexr -Deverloper discussion mailing list: +* Documentation: http://www.openexr.com/documentation.html. -* [openexr-dev@lists.aswf.io](https://lists.aswf.io/g/openexr-dev) +* Deverloper discussion mailing list: [openexr-dev@lists.aswf.io](https://lists.aswf.io/g/openexr-dev) -## Building and Installation +## Developer Quick Start Download the latest release of OpenEXR from the GitHub Releases page: https://github.com/openexr/openexr/releases. -For more information about building from sources, see the [INSTALL.md](INSTALL.md) file. +For the basic installation on Linux: + + cd /IlmBase + ./configure + make + make install + + cd /OpenEXR + ./configure + make + make install + +See the module README files for options to ``configure``. + +See the [build documentation](INSTALL.md) documentation for help with +installation on other platforms. ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for more information about contributing to OpenEXR. +Developers who wish to contribute code to be considered for inclusion +in the OpenEXR distribution must first complete the Contributor +License Agreement and submit it to info@openexr.com. We prefer code +submissions in the form of pull requests to this repository. Every +commit must be signed off. That is, every commit log message must +include a “Signed-off-by” line (generated, for example, with “git +commit --signoff”), indicating that the committer wrote the code and +has the right to release it under the BSD-3-Clause license. See +http://developercertificate.org/ for more information on this +requirement. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for more information about +contributing to OpenEXR. ## Project Goverance -OpenEXR is owned by the Academy Software Foundation, and is maintained -by the developer community. See [GOVERNANCE.md](GOVERNANCE.md) for -more infomation. +OpenEXR is governed by the Academy Software Foundation. See +[GOVERNANCE.md](GOVERNANCE.md) for more infomation. ## Documentation From dd63edb44447441f45eda61ba3a40029b5968a3a Mon Sep 17 00:00:00 2001 From: xlietz <31363633+xlietz@users.noreply.github.com> Date: Wed, 12 Jun 2019 00:21:56 -0700 Subject: [PATCH 08/10] fixing minor typos --- CONTRIBUTING.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6281d25e3..895bc5ad68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ technical conversations and decisions that have shaped the project. ### How to Ask for Help -If you have trouble installing, building, or using the library, but there's not yet reason to suspect you've encountered a genuine but, start by posting a question to the [openexr-dev](http://lists.aswf.io/openexr-dev) mailing list. This is the place for question such has "How do I...". +If you have trouble installing, building, or using the library, but there's not yet reason to suspect you've encountered a genuine bug, start by posting a question to the [openexr-dev](http://lists.aswf.io/openexr-dev) mailing list. This is the place for question such has "How do I...". ### How to Report a Bug @@ -26,7 +26,7 @@ https://github.com/openexr/openexr/issues If you are submitting a bug report, please be sure to note which version of OpenEXR you are using, on what platform (OS/version, which compiler you used, and any special build flags or other unusual -environmental issues). Please give a specific an account of +environmental issues). Please give a specific account of * what you tried * what happened @@ -66,7 +66,7 @@ See below for details. OpenEXR is owned by the Academy Software Foundation and follows the open source software best practice policies of the Linux Foundation. -### Contributor Licence Agreements +### Contributor License Agreements Developers who wish to contribute code to be considered for inclusion in the OpenEXR distribution must first complete a **Contributor @@ -157,15 +157,15 @@ workflow. ### Use the Fork, Luke. -In a typical workflow, yous should **fork** the OpenEXR repository to +In a typical workflow, you should **fork** the OpenEXR repository to your account. This creates a copy of the repository under your user namespace and serves as the “home base” for your development branches, from which you will submit **pull requests** to the upstream repository to be merged. Once your Git environment is operational, the next step is to locally -**clone** your forked OpenColorIO repository, and add a **remote** -pointing to the upstream OpenColorIO repository. These topics are +**clone** your forked OpenEXR repository, and add a **remote** +pointing to the upstream OpenEXR repository. These topics are covered in [Cloning a repository](https://help.github.com/articles/cloning-a-repository/) and [Configuring a remote for a @@ -369,7 +369,7 @@ going on in your code. Prefer C++ comments (starting line with `//`) rather than C comments (`/* ... */`). For public APIs we tend to use Doxygen-style comments (start with `///`). -They looks like this: +They look like this: /// Explanation of a class. Note THREE slashes! /// Also, you need at least two lines like this. If you don't have enough @@ -403,7 +403,7 @@ Guidelines](http://opencolorio.org/developers/documentation_guidelines.html). OpenEXR uses [semantic versioning](https://semver.org), which labels each version with three numbers: Major.Minor.Patch, where: -* **MAJOR** indicates incompatible API changes, +* **MAJOR** indicates incompatible API changes * **MINOR** indicates functionality added in a backwards-compatible manner * **PATCH** indicates backwards-compatible bug fixes From cf528b290391a9d3b8517587130c193dc3d4555c Mon Sep 17 00:00:00 2001 From: seabeepea Date: Wed, 12 Jun 2019 15:40:22 -0700 Subject: [PATCH 09/10] hello, world --- azure-pipelines.yml | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 azure-pipelines.yml diff --git a/azure-pipelines.yml b/azure-pipelines.yml new file mode 100644 index 0000000000..8899362160 --- /dev/null +++ b/azure-pipelines.yml @@ -0,0 +1,5 @@ +pool: + vmImage: 'Ubuntu 16.04' +steps: +- script: echo Hello, world! + displayName: 'Hello World' \ No newline at end of file From 9bbdeff8a2af539f67e9e03313ea5cc51b019256 Mon Sep 17 00:00:00 2001 From: Cary Phillips Date: Fri, 14 Jun 2019 14:57:54 -0700 Subject: [PATCH 10/10] - Formatting section is TBD - fixed references to license - removed references to CI - added section on GitHub labels Signed-off-by: Cary Phillips --- CONTRIBUTING.md | 142 ++++++++++++++++++------------------------------ 1 file changed, 54 insertions(+), 88 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 895bc5ad68..7554963e35 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,10 +98,10 @@ projects. Every commit must be signed off. That is, every commit log message must include a “`Signed-off-by`” line (generated, for example, with “`git commit --signoff`”), indicating that the committer wrote the -code and has the right to release it under the [MPL -2.0](https://www.mozilla.org/MPL/2.0/) license. See -http://developercertificate.org/ for more information on this -requirement. +code and has the right to release it under the +[Modified-BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) +license. See http://developercertificate.org/ for more information on +this requirement. ## Development Workflow @@ -166,7 +166,7 @@ repository to be merged. Once your Git environment is operational, the next step is to locally **clone** your forked OpenEXR repository, and add a **remote** pointing to the upstream OpenEXR repository. These topics are -covered in [Cloning a +covered in the GitHub documentation [Cloning a repository](https://help.github.com/articles/cloning-a-repository/) and [Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/), @@ -177,7 +177,7 @@ openexr-dev@lists.aswf.io mail list. Contributions should be submitted as Github pull requests. See [Creating a pull request](https://help.github.com/articles/creating-a-pull-request/) -if you're unfamiliar with this concept. +if you're unfamiliar with this concept. The development cycle for a code change should follow this protocol: @@ -193,23 +193,14 @@ with a separate pull request. 4. Create a Github pull request from your topic branch. -5. All pull requests trigger CI builds on [Travis CI](https://travis-ci.org/) -for Linux and Mac OS and [AppVeyor](https://www.appveyor.com/) for Windows. -These builds verify that code compiles and all unit tests succeed. CI build -status is displayed on the GitHub PR page, and changes will only be considered -for merging after all builds have succeeded. - -6. Pull requests will be reviewed by project Committers and Contributors, +5. Pull requests will be reviewed by project Committers and Contributors, who may discuss, offer constructive feedback, request changes, or approve the work. -7. Upon receiving the required number of Committer approvals (as outlined -in [Required Approvals](#required-approvals)), a Committer other than the PR -contributor may squash and merge changes into the master branch. - -See also (from the OpenEXR Developer Guide): -* [Getting started](http://opencolorio.org/developers/getting_started.html) -* [Submitting Changes](http://opencolorio.org/developers/submitting_changes.html) +6. Upon receiving the required number of Committer approvals (as +outlined in [Required Approvals](#required-approvals)), a Committer +other than the PR contributor may merge changes into the master +branch. ### Code Review and Required Approvals @@ -269,97 +260,76 @@ modifications to the TSC by assigning the `tsc-review` label to a pull request or issue. The TSC should serve as the final arbiter where required. -## Coding Style +### Project Issue Handling Process -#### Formatting +Incoming new issues are labeled promptly by the TSC using GitHub labels. -We use [clang-format](https://clang.llvm.org/docs/ClangFormat.html) -to uniformly format our source code prior to PR submission. Make sure that -clang-format is installed on your local machine, and just run +The labels include: - make clang-format +* **Bug** - A bug in the source code. Something appears to be + functioning improperly: a compile error, a crash, unexpected behavior, etc. -and it will automatically reformat your code according to the configuration -file found in the `.clang-format` file at the root directory of the OpenEXR -source code checkout. +* **Build/Install Issue** - A problem with building or installing the + library: configuration file, external dependency, a compile error + with a release version that prevents installation. -One of the TravisCI test matrix entries runs clang-format and fails if any -diffs were generated (that is, if any of your code did not 100% conform to -the `.clang-format` formatting configuration). If it fails, clicking on that -test log will show you the diffs generated, so that you can easily correct -it on your end and update the PR with the formatting fixes. +* **C++** - A C++ compilation issue: a compiler warning, syntax issue, + or language usage or suggested upgrade. -If you don't have clang-format set up on your machine, and your patch is not -very long, you may find that it's more convenient to just submit it and hope -for the best, and if it doesn't pass the Travis test, look at the diffs in -the log and make the corrections by hand and then submit an update to the -patch (i.e. relying on Travis to run clang-format for you). +* **CMake** - A build issue with the CMake configuration files. -Because the basic formatting is automated by clang-format, we won't -enumerate the rules here. +* **CVE** - A security vulnerability bug. -#### File conventions +* **Documentation** - The project documentation: developer or user guide, web site, project policies, etc. -C++ implementation should be named `*.cpp`. Headers should be named `.h`. -All headers should contain +* **Feature Request** - A suggested change or addition of functionality to the library. - #pragma once +* **MinGW** - An issue specific to MinGW -All source files should begin with the copyright and license, which -can be found in the [LICENSE](LICENSE.md) file (or cut and pasted from -any other other source file). +* **Mac OS** - A build issue specific to Mac OS. -For NEW source files, please change the copyright year to the present. DO -NOT edit existing files only to update the copyright year, it just creates -pointless deltas and offers no increased protection. +* **Pending merge to master** +* **Question/Problem/Help** - A request for help or further investigation, possibly just user error or misunderstanding. -#### Identifiers +* **Test Failure** - One of the automated tests is failing, or an analysis tool is reporting problematic behavior. -In general, classes and templates should start with upper case and -capitalize new words: `class CustomerList;` In general, local variables -should start with lower case. Macros should be `ALL_CAPS`, if used at all. +* **Windows** - A build issue specific to Windows -If your class is extremely similar to, or modeled after, something in the -standard library, Boost, or something else we interoperate with, it's ok to -use their naming conventions. For example, very general utility classes and -templates (the kind of thing you would normally find in std or boost) should -be lower case with underscores separating words, as they would be if they -were standards. +* **Won't Fix** - No further action will taken. - template shared_ptr; - class scoped_mutex; +## Coding Style -Names of data should generally be nouns. Functions/methods are trickier: a -the name of a function that returns a value but has no side effects should -be a noun, but a procedure that performs an action should be a verb. +#### Formatting + +TBD -#### Class structure +#### File conventions + +C++ implementation should be named `*.cpp`. Headers should be named `.h`. +All headers should contain -Try to avoid public data members, although there are some classes that serve -a role similar to a simple C struct -- a very straightforward collection of -data members. In these, it's fine to make the data members public and have -clients set and get them directly. + #pragma once -Private member data should be named m_foo (alternately, it's ok to use the -common practice of member data foo_, but don't mix the conventions within a -class). +#### Copyright Notices -Private member data that needs public accessors should use the convention: +All new source files should begin with a copyright and license stating: - void foo (const T& newfoo) { m_foo = newfoo; } - const T& foo () const { return m_foo; } + // SPDX-License-Identifier: Modified-BSD-3-Clause + // Copyright Contributors to the OpenEXR Project. See LICENSE file for details. -Avoid multiple inheritance. +#### Identifiers -Namespaces: yes, use them! +In general, classes and templates should start with upper case and +capitalize new words: `class CustomerList;` In general, local +variables should start with lower case. Macros should be `ALL_CAPS`, +if used at all. #### Third-party libraries -Prefer C++11 `std` rather than Boost, where both can do the same task. -Feel free to use Boost classes you already see in the code base, but don't -use any Boost you don't see us already using, without first checking with -the project leader. +Prefer C++11 `std` over Boost where possible. Feel free to use Boost +classes you already see in the code base, but check with the project +leadership before adding new boost usage. #### Comments and Doxygen @@ -368,8 +338,7 @@ going on in your code. Prefer C++ comments (starting line with `//`) rather than C comments (`/* ... */`). -For public APIs we tend to use Doxygen-style comments (start with `///`). -They look like this: +For public APIs, use Doxygen-style comments (start with `///`), such as: /// Explanation of a class. Note THREE slashes! /// Also, you need at least two lines like this. If you don't have enough @@ -393,9 +362,6 @@ When in doubt, look elsewhere in the code base for examples of similar structures and try to format your code in the same manner, or ask on the openexr-dev mail list. -For standards on contributing to documentation, see the [Documentation -Guidelines](http://opencolorio.org/developers/documentation_guidelines.html). - ## Release Management ### Versioning Policy