diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..16136ae7 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,185 @@ +# Code of Conduct + +## Our purpose + +CIMTool is an open-source project maintained under the stewardship of the +[UCA International Users Group (UCAIug)](https://cimug.ucaiug.org/). Its +contributors and users include utility engineers, vendor staff, researchers, +standards participants, and independent practitioners, working across many +countries, organizations, and native languages. + +We want CIMTool to be a project where a contribution is judged on its merits and +its fit with the project's direction, never on who is offering it, and where anyone +with something useful to offer can offer it without first having to prove they +belong. + +This document states what we expect of participants, what we will not tolerate, +and what happens when the line is crossed. + +## Scope + +This Code of Conduct applies to all project spaces, including the CIMTool +repositories, issues, pull requests, discussions, commit messages, code review +comments, and the project's documentation sites. It also applies when an +individual is representing the project in public, whether at a conference, in a +CIM Users Group session, on a mailing list, or on social media. + +Participation in UCAIug meetings and working groups is additionally governed by +UCAIug's own policies. Where the two overlap, both apply. + +## Expected behavior + +Participants in this project are expected to: + +- **Assume good faith.** Contributors come from very different engineering + cultures. A blunt review comment is more often a language difference than an + insult. Read charitably before responding. +- **Keep disagreement technical.** Criticize the design, the code, or the + reasoning. Not the person who produced it. "This breaks single inheritance in + the profile model" is a review. "You clearly don't understand CIM" is not. +- **Accept review gracefully.** Having your work critiqued is the point of + review, not a cost of it. Maintainers, likewise, owe contributors reviews that + explain rather than merely reject. +- **Be patient with newcomers.** Everyone writing XSLT builders today was once + someone who had never opened one. The project's future depends on that + transition continuing to happen. +- **Respect the time of others.** Search before filing. Read the contributing + guidelines before opening a pull request. Provide reproduction steps. +- **Take responsibility for mistakes.** Apologize, correct, and move on. This + applies to maintainers at least as much as to contributors. + +## Unacceptable behavior + +The following are not tolerated in any project space: + +- Harassment of any kind, whether public or private, including unwelcome + attention after a request to stop. +- Insults, personal attacks, and derogatory comments, including those directed + at a person's employer, nationality, or perceived level of expertise. +- Discriminatory language or conduct relating to age, body size, disability, + ethnicity, gender identity or expression, level of experience, nationality, + personal appearance, race, religion, or sexual identity or orientation. +- Sexualized language or imagery, and sexual attention of any kind. +- Publishing another person's private information, such as a home address, a + personal email address, or an employer's internal information, without their + explicit permission. +- Sustained disruption of discussion, deliberate intimidation, or trolling. +- Advocating for or encouraging any of the above. + +Two clarifications, because this is an engineering project and the line is +sometimes drawn in the wrong place: + +**Technical disagreement is not harassment.** Rejecting a pull request, +questioning an approach, insisting on evidence, or holding a contribution to the +project's conventions are all legitimate and expected. A contributor whose work +is declined has not been mistreated. + +**Persistent, targeted hostility is harassment even when it is dressed as +technical critique.** The distinction is whether the conduct is directed at the +work or at the person. + +## Conflicts of interest + +CIMTool contributors frequently work for organizations that compete with one +another, and some contribute to standards that CIMTool implements. This is +normal and welcome. It becomes a problem only when it is concealed. + +If you have a commercial or standards-related interest in the outcome of a +technical decision, disclose it on the relevant issue or pull request. Using the +project to advantage an employer, disparage a competitor, or steer an +implementation away from the published standard is unacceptable. + +Using CIMTool in the course of your work, and filing enhancement requests that arise +from that use, is not a conflict of interest and requires no disclosure. It is how +the project learns what it is missing, and requests of this kind are welcome from +every organization, the corporate sponsor included. They are judged on their merits +alongside all others. The disclosure obligation concerns an interest in the +*outcome* of a decision that is separate from the merits of the tool itself: a +commercial stake in one resolution over another, or a position in a standards body +that the decision would affect. + +## Security and responsible disclosure + +Publicly disclosing a security vulnerability in CIMTool before maintainers have +had a reasonable opportunity to respond is a violation of this Code of Conduct. The +cost of a premature disclosure is not borne by this project. It is borne by the +organizations running CIMTool in production, who have no fix to apply and no warning +that they need one. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for how to report a vulnerability +privately. + +## Reporting + +If you experience or witness behavior that violates this Code of Conduct, report +it to the project maintainers at +[cimtool-conduct@ucaiug.org](mailto:cimtool-conduct@ucaiug.org). + +Include, as far as you are able: + +- What happened, and where. Links to the relevant issue, pull request, or + comment are the most useful thing you can provide. +- Whether the conduct is ongoing. +- Any context you believe is relevant, including prior incidents. + +You do not need to be the target of the behavior to report it. + +**If your report concerns a project maintainer**, or if for any reason you are +not comfortable using that address, contact the UCAIug directly at +[github.admin@ucaiug.org](mailto:github.admin@ucaiug.org). + +## Confidentiality + +Reports are treated as confidential. We will not disclose the identity of a +reporter without their consent, except where we are legally obliged to do so, or +where a person's safety is at immediate risk. + +We will acknowledge a report promptly and tell you what we intend to do. We may +not always be able to tell you the outcome, since the subject of a report is +also entitled to a degree of privacy. + +Reporting in bad faith, whether to retaliate against someone or to manufacture a +grievance, is itself a violation of this Code of Conduct. + +## Enforcement + +Maintainers are responsible for clarifying and enforcing this Code of Conduct. +They may edit, hide, or delete comments, commits, code, issues, and pull +requests that violate it, and will explain their reasoning when they do so. + +Responses are proportionate. In escalating order: + +1. **Private correction.** A private message explaining what was wrong and why. + Most incidents end here, and most people who receive one adjust. + +2. **Warning.** A formal warning, with consequences stated. This may include a + period during which the person is asked not to interact with those involved, + including in project spaces and unsolicited outside them. + +3. **Temporary suspension.** A defined period without participation in project + spaces. Contributions submitted during a suspension will not be reviewed. + +4. **Permanent exclusion.** Reserved for sustained violation, harassment of an + individual, or aggression toward a class of people. This is rare and it is + final. + +Maintainers who violate this Code of Conduct face the same consequences as +anyone else, escalated rather than mitigated by their position. A maintainer who +cannot be held to the standard they enforce should not be a maintainer. + +## Appeals + +A person subject to enforcement action may appeal by writing to +[github.admin@ucaiug.org](mailto:github.admin@ucaiug.org) within thirty days, +setting out why they believe the action was mistaken or disproportionate. The +appeal will be considered by someone who was not involved in the original +decision. + +## Attribution + +This Code of Conduct is original to the CIMTool project. It draws on ideas +common to the [Contributor Covenant](https://www.contributor-covenant.org/) and +other widely adopted community standards, and it is offered under the same terms +as the project itself. + +Suggestions for improving it are welcome. Open an issue. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..d6648ef5 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,424 @@ +# Contributing to CIMTool + +Thank you for your interest in contributing. CIMTool is an open-source project +maintained under the stewardship of the [UCA International Users Group +(UCAIug)](https://cimug.ucaiug.org/). Contributions from the CIM community are +welcome and encouraged. + +This document describes how work is organized, how to get your changes +accepted, and the conventions we ask you to follow. Please read it before +opening your first pull request. + +--- + +## Table of contents + +- [Before you start](#before-you-start) +- [Branching model](#branching-model) +- [Fork or branch?](#fork-or-branch) +- [Branch naming](#branch-naming) +- [Commit messages](#commit-messages) +- [Pull requests](#pull-requests) +- [Keeping your branch current](#keeping-your-branch-current) +- [Continuous integration](#continuous-integration) +- [Code review and merge](#code-review-and-merge) +- [Reporting security vulnerabilities](#reporting-security-vulnerabilities) +- [Licensing and provenance](#licensing-and-provenance) + +--- + +## Before you start + +**Every contribution begins with an issue.** Our branch naming and commit +conventions are built around issue numbers, so an issue must exist before work +begins. + +1. Search the [issue tracker](https://github.com/cimug-org/CIMTool/issues) to see + whether your enhancement or defect has already been reported. +2. If it has not, open a new issue describing the enhancement or defect. For + defects, include the CIMTool version, your platform, and steps to reproduce. +3. Wait for a maintainer to triage and label the issue. This avoids duplicated + effort and confirms the change fits the project's direction before you + invest time in it. +4. If you would like the issue assigned to you, say so in a comment. + +Substantial changes, such as new builders, changes to the profile model, or +anything affecting generated artifacts, should be discussed on the issue before +implementation. We would much rather talk through a design than ask you to +rewrite three hundred lines of XSLT. + +**Scope is a legitimate reason to decline.** CIMTool has a direction, and not every +good idea belongs in it. Where a proposed enhancement does not fit that direction, a +maintainer will say so on the issue and will explain why. This is not a judgment on +the quality of the idea, still less on you. It is far better that you hear it before +you write the code than after, which is why we ask that substantial changes be +discussed first. You remain free to carry the change in your own fork. + +--- + +## Branching model + +CIMTool uses a feature-branch workflow built on two kinds of long-lived branch. + +| Branch | Purpose | +| --- | --- | +| `master` | Released code only. Every public release is a tagged commit on `master`. Never targeted directly by code contributions; repository governance files may be committed directly by maintainers. | +| `release-` | The development branch for the next release. Cut from `master` immediately after each public release. **All contributions target the current release branch.** | + +### Development branch naming + +The development branch is named for the release it will eventually become. It +is created from `master` as soon as the preceding release goes public and is +tagged. + +``` +release-2.3.0 +release-2.4.0 +``` + +Where a release candidate is being prepared, the candidate designation is +appended: + +``` +release-2.4.0.RC1 +release-2.4.0.RC2 +``` + +**There is exactly one development branch open for contributions at a time.** +It is always the highest-versioned `release-*` branch in the repository. If you +are unsure which one that is, check the +[branch list](https://github.com/cimug-org/CIMTool/branches) or ask on the issue +before you begin. + +Throughout the remainder of this document, `release-2.4.0` is used as a stand-in +for whichever release branch is currently open. Substitute the actual branch +name. + +### Lifecycle + +Individual contributions are made on short-lived branches taken from the current +release branch and merged back into it via pull request. When the release is +ready, the release branch is merged to `master`, `master` is tagged, and a new +release branch is cut for the next cycle. + +``` +master ──●─────────────────────────────────────────●───────────> + │ tag: v2.3.0 │ tag: v2.4.0 + │ │ + └── release-2.4.0 ──●────●────●────●────●─┘ + │ ▲ │ ▲ + │ │ │ │ + enhancement-issue-269 ─┘ │ │ + defect-issue-288 ─┘ +``` + +--- + +## Fork or branch? + +Both are supported. The choice depends on your access level, not your +preference for one workflow over another. + +**Contributors without write access** (the common case) should fork the +repository and work on a branch in their fork. This requires no special +permissions and is the standard open-source path. + +**Maintainers and committers with write access** may create branches directly +in the main repository. + +The conventions in this document, covering branch naming, commit messages, and +pull request content, apply identically in both cases. A fork does not exempt +you from them. We simply cannot enforce them technically on a repository we do +not control, so we ask that you apply them yourself. + +Note that pull requests from forks run a restricted CI pipeline. See +[Continuous integration](#continuous-integration). + +--- + +## Branch naming + +Name your branch after the issue it addresses: + +``` +enhancement-issue- +defect-issue- +``` + +For example: + +``` +enhancement-issue-269 +defect-issue-288 +``` + +Note that your working branch is named for the *issue*, not for the release. +Only the development branch it targets carries a version number. + +One issue per branch. If you find yourself fixing an unrelated defect along the +way, open a separate issue and a separate branch for it. Mixed-purpose branches +are difficult to review and impossible to revert cleanly. + +--- + +## Commit messages + +### Reference the issue in every commit + +Every commit must reference the issue it addresses. Which form you use depends +on where you are working. + +**Working in the main repository** (maintainers and committers with write +access). The short form is sufficient: + +``` +#269 Add oppositeOf resolution to shadow class URIs +``` + +**Working in a fork** (all other contributors). Please use the fully-qualified +form: + +``` +cimug-org/CIMTool#269 Add oppositeOf resolution to shadow class URIs +``` + +This matters because GitHub resolves a bare `#269` relative to whichever +repository you are viewing the commit in. A commit written in the main +repository resolves as intended. The same commit written in your fork points at +issue 269 *in your fork*, which does not exist, or worse, will someday exist and +be something else entirely. The fully-qualified `cimug-org/CIMTool#269` form resolves +correctly from anywhere, both in your fork during review and in the main +repository after merge. + +### Structure + +In the main repository: + +``` +#269 Short imperative summary, 72 characters or less + +Explain what changed and why. Wrap at 72 columns. The summary line +should stand on its own; a reader should not need to open the issue +to understand what the commit does. +``` + +In a fork: + +``` +cimug-org/CIMTool#269 Short imperative summary, 72 characters or less + +Explain what changed and why. Wrap at 72 columns. The summary line +should stand on its own; a reader should not need to open the issue +to understand what the commit does. +``` + +Because we do not squash on merge, your commits arrive in the main repository +with their messages intact. The reference you write is the reference a +maintainer reads two releases from now. + +### What not to do + +Do **not** use closing keywords (`Fixes`, `Closes`, `Resolves`) in commit +messages. GitHub only honors them when a commit reaches the repository's +default branch, and our contributions land on a release branch, not on +`master`. The keyword would either do nothing or fire at an unexpected time. +Put closing keywords in the pull request description instead, as described +below. + +--- + +## Pull requests + +Open your pull request against the **current release branch** of `cimug-org/CIMTool`, +for example `release-2.4.0`. Pull requests opened against `master` will be +closed and you will be asked to retarget them. + +The pull request is the durable record linking your work to the issue. It lives +in the main repository, appears in the issue's timeline, and survives long +after anyone remembers which fork the branch came from. Treat the description +as the thing a future maintainer will read. + +Include in the description: + +- **`Fixes cimug-org/CIMTool#269`** (or `Closes`, `Resolves`). This creates the formal + linked-pull-request relationship that GitHub tracks. Use one keyword per + issue closed. +- A summary of the change and the approach taken. +- Anything a reviewer needs to know to exercise the change: build steps, test + data, affected builders or profiles. +- Screenshots for UI changes. + +Before requesting review: + +- [ ] The branch is rebased on the current release branch. +- [ ] The full build passes locally. +- [ ] New or changed behavior is covered by tests where the surrounding code is + tested. +- [ ] Generated artifacts have been regenerated and inspected if the change + affects a builder. +- [ ] Documentation is updated if the change is user-visible. + +Draft pull requests are welcome and encouraged for work in progress. Mark them +ready for review when you would like a maintainer to look. + +--- + +## Keeping your branch current + +Rebase onto the current release branch. Do not merge the release branch into +your feature branch. + +```bash +# One-time setup, from your fork's clone +git remote add upstream https://github.com/cimug-org/CIMTool.git + +# Whenever the release branch has moved +git fetch upstream +git rebase upstream/release-2.4.0 +git push --force-with-lease origin enhancement-issue-269 +``` + +Use `--force-with-lease` rather than `--force`, because it refuses to overwrite +work you have not seen. Force-pushing to your own feature branch is expected and +fine. Force-pushing to a release branch or to `master` is not. + +A rebased branch produces a linear, reviewable history. A branch with the +release branch merged into it repeatedly produces a history nobody can read. + +If your work spans a release boundary and the branch you targeted has since +merged to `master`, rebase onto the new release branch and retarget the pull +request. Notify the maintainers on the issue if this is likely to happen. + +--- + +## Continuous integration + +CIMTool does not presently run an automated build or test pipeline on pull +requests. The repository's only workflow builds and publishes the documentation +site when a commit lands on `master`, and it runs on no other branch and on no +pull request. + +You are therefore responsible for building your change and running the tests +locally before requesting review. A reviewer will ask what you ran. The checklist +above is not a formality. + +Release artifacts are built, signed, and published outside of continuous +integration, by a representative vetted and approved by the UCA International Users +Group. CIMTool is signed with an Extended Validation certificate whose private key +resides on a hardware token and never leaves it. The signing credentials are +therefore never present on a runner, in a workflow, or in a repository secret, and +no pull request, whether from a fork or from a branch in this repository, can reach +them. The procedure is documented in +[CIMToolProduct-README.md](dev-docs/Includes/CIMToolProduct/CIMToolProduct-README.md#phase-3-code-signing-and-packaging). + +If your change touches the build, packaging, or signing configuration, say so +explicitly in the pull request. A maintainer will validate it before release. + +--- + +## Code review and merge + +At least one maintainer approval is required before merge. This applies to +contributors who hold write access to the repository as much as to those working +from a fork: write access permits branch creation and pushes to your own branch, +never a merge to `master` or to a release branch. + +Repository administrators may merge their own pull request without a second +approval, and only where review is impractical. This is the sole exception. It does +not waive the requirement to open a pull request, and it does not permit pushing, +force-pushing, or deleting a protected branch. A pull request merged without an +approving review says so, on the record, permanently. + +Maintainers may push commits to branches in the main repository. If you are working from a fork, +enabling **"Allow edits by maintainers"** on your pull request lets us fix a +typo or rebase for you rather than sending you round for another iteration. +This option is not available on pull requests from organization-owned forks. + +**Merge strategy.** Pull requests are merged with a merge commit. Squash merging +and rebase merging are both disabled on this repository, and this is deliberate +rather than incidental. + +Squashing collapses your individual commits into one and discards the per-commit +issue references, which is precisely the traceability the commit conventions above +exist to preserve. Rebase merging keeps those commits but replays them directly +onto the release branch, which places any intermediate, non-building commit onto +the mainline where it cannot be distinguished from a reviewed one. + +A merge commit avoids both problems. Your commits arrive intact, and the mainline +retains one merge node per reviewed pull request. A maintainer bisecting a +regression can therefore restrict the search to reviewed, buildable states: + +```bash +git bisect start --first-parent +git bisect bad release-2.4.0 +git bisect good CIMTool-2.3.0 +``` + +This works only because the merge nodes exist. It is the reason the setting is +what it is, and the reason we ask you to curate your branch rather than relying +on the merge button to do it for you. + +**Curate your history before requesting review.** A handful of coherent commits is +ideal. Checkpoint commits, and noise commits such as "fix typo", "wip", or +"address review comments", should be squashed into their parents by you, on your +branch, before merge. Every commit that lands should build. If you would rather a +maintainer tidied the branch for you, enable "Allow edits by maintainers" and ask. + +--- + +## Reporting security vulnerabilities + +Do **not** open a public issue for a security vulnerability. + +Report it privately using [GitHub's private vulnerability +reporting](https://github.com/cimug-org/CIMTool/security/advisories/new), which +opens a confidential thread visible to you and to the project's maintainers and +committers, and not to the public. This is the preferred channel. + +If you are unable to use GitHub, you may instead email +[cimtool-security@ucaiug.org](mailto:cimtool-security@ucaiug.org). + +We will acknowledge receipt and coordinate disclosure with you. + +This includes vulnerabilities in CIMTool's dependencies where CIMTool's +configuration exposes them. + +--- + +## Licensing and provenance + +CIMTool is distributed under the GNU Lesser General Public License v2.1 +(LGPL-2.1); see [LICENSE](LICENSE). By +contributing, you certify that you have the right to submit your contribution +under that license and that you agree to do so. + +Sign off each commit to indicate this, in accordance with the [Developer +Certificate of Origin](https://developercertificate.org/): + +```bash +git commit -s -m "cimug-org/CIMTool#269 Add oppositeOf resolution to shadow class URIs" +``` + +This appends a `Signed-off-by:` trailer to your commit message. Contributions +without a sign-off cannot be merged. + +If your contribution is made in the course of employment, please ensure your +employer is aware and permits it. Contributions submitted on behalf of a member +organization of the UCAIug remain subject to the applicable UCAIug intellectual +property policy. + +--- + +## Code of conduct + +Participation in this project is governed by our +[Code of Conduct](CODE_OF_CONDUCT.md). Be civil, assume good faith, and keep +disagreement technical. + +--- + +## Questions + +Open a [discussion](https://github.com/cimug-org/CIMTool/discussions) or raise the +matter at a CIM Users Group meeting. We are a small project and we would rather +answer a question early than review a misdirected pull request late. diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md new file mode 100644 index 00000000..d319e2dc --- /dev/null +++ b/.github/GOVERNANCE.md @@ -0,0 +1,250 @@ +# CIMTool Governance + +## Stewardship + +CIMTool is an open-source project of the +[UCA International Users Group (UCAIug)](https://cimug.ucaiug.org/), maintained +under the CIMug Open Source Initiative. The UCAIug holds the project's +repositories and sets the policies under which they operate. Day-to-day +technical direction rests with the project maintainers. + +CIMTool serves the IEC TC57 community. Where a technical decision touches a +published standard, the standard governs. CIMTool implements standards; it does +not define them. + +## Corporate sponsorship + +**Emerson/AspenTech is the official corporate sponsor of CIMTool** and develops +the tool on behalf of the UCA CIM Users Group. Sponsorship funds sustained +maintainer effort that an entirely unfunded project could not supply. + +Not every maintainer or regular contributor is employed by the sponsor. CIMTool +is developed by sponsored and unpaid contributors working alongside one another, +and this document draws no distinction between them. Contributions are judged on +their technical merits, not on who paid for the time that produced them. + +The boundary is as follows, and it is not merely a formality: + +- **Sponsorship does not confer ownership.** The repositories, the trademarks, and + the project's direction belong to the UCAIug. +- **Sponsorship does not confer authority over contributions.** A pull request + from a sponsor employee is reviewed on the same terms as one from any other + contributor, and is subject to the same conventions and the same right of + refusal. +- **Sponsorship does not make CIMTool a commercial product.** CIMTool is + distributed free of charge under an open-source license, with no warranty and + no support obligation. See [SUPPORT.md](SUPPORT.md). +- **Sponsorship does not entitle the sponsor to steer CIMTool toward its own + products.** Where a technical decision would advantage a sponsor product over a + competing implementation of the same standard, the standard governs and the + decision is made in public on the relevant issue. + +That boundary is maintained architecturally rather than by assurance. Where a +vendor requires a capability specific to its own commercial products, that +capability is developed and distributed separately from CIMTool rather than merged +into it. CIMTool provides the general mechanism, such as the ability to author and +import custom builders; a builder targeting a proprietary format is shipped by its +vendor, not by this project. This applies to every vendor, and the corporate sponsor +is not exempt from it. + +The test a maintainer applies is whether a proposed capability serves the CIM +community generally or serves one vendor's product in particular. The first belongs +in CIMTool. The second belongs outside it, and the mechanism that makes it possible +belongs in CIMTool. + +Maintainers employed by the sponsor are bound by the conflict-of-interest +provisions of the [Code of Conduct](CODE_OF_CONDUCT.md) in the same way as any +other participant, and the disclosure obligation applies to them with particular +force. A maintainer who is also a sponsor employee discloses that interest where +it is material and does not rely on it being generally known. + +The UCAIug may end the sponsorship relationship. The project would continue. + +## Roles + +### Users + +Anyone who uses CIMTool. Users contribute by reporting defects, requesting +enhancements, asking and answering questions in Discussions, and telling +maintainers what the tool gets wrong. + +### Contributors + +Anyone who submits a pull request, improves documentation, contributes an XSLT +builder to the Builders Library, or otherwise materially helps the project. No +formal status is required and none is conferred. Contributors work from forks +unless they hold write access. + +### Committers + +Committers hold write access to the repository. Write access permits a committer +to create branches, push to their own branches, and open pull requests from +within the repository rather than from a fork. It does not permit merging. + +**A committer cannot land a change without a maintainer's review.** Every change +reaches `master` or a release branch through a reviewed pull request. This applies +to committers and maintainers alike, and it applies to sponsored and volunteer +contributors alike. + +Committers may be volunteers with no employment relationship to the corporate +sponsor. Write access reflects sustained, trustworthy contribution, not +affiliation. + +Current committers: + +- Bart Kleijngeld (@bartkl) +- Dan F (@dfeldman987) +- Yunshu (@pluckySquid) +- Máté Zsebeházi (@MateZsebehazi) + +### Maintainers + +Maintainers hold write access and, in addition, the authority to approve and merge +pull requests. They triage issues, make release decisions, and enforce the +[Code of Conduct](CODE_OF_CONDUCT.md). + +**Maintainers are the project's code owners.** The `cimtool-maintainers` team is +named in [CODEOWNERS](.github/CODEOWNERS), and the "Protected branches" ruleset +requires an approving review from a code owner before a pull request can be merged. +A committer's approval, however sound, does not satisfy that requirement. This is +the mechanism by which the Committer and Maintainer roles differ in practice rather +than merely in name. + +More than one person may hold this role. At present only one does. Maintainer +status requires a depth of familiarity with the CIMTool codebase that takes +substantial time to develop, and the project will not confer merge authority on +someone who is not yet in a position to exercise it well. Growing a second +maintainer is an active goal, approached through mentoring rather than through +appointment. + +Maintainers seek review of their own work as a matter of course, and a maintainer +who can reasonably wait for a reviewer waits. The lead maintainer, who holds +repository administrator rights, may merge their own pull request without a second +approval only where review is impractical. + +This exception is narrow and it is deliberate. It does not permit pushing directly +to `master` or to a release branch, and it does not permit force-pushing or +deleting either. Every change reaches those branches through a pull request, and +the pull request record, including the absence of an approving review, stands as +the audit trail. + +Current maintainers: + +- Todd Viegut (@tviegut) + +### Lead maintainer + +The lead maintainer is a maintainer who additionally carries responsibilities that +fall to one person rather than to the group: + +- Release management, including the decision to cut a release branch, promote a + release candidate, and publish a release. +- Custody of the code signing credentials and the signing of release artifacts. +- Resolution of technical disagreements that the maintainers cannot settle among + themselves. +- Serving as the project's point of contact with the UCA International Users Group. + +Only one person holds this role at a time. The lead maintainer is a maintainer +first, and the additional responsibilities confer no different kind of authority +over contributions: a pull request from the lead maintainer is reviewed on the same +terms as any other. + +The lead maintainer is Todd Viegut (@tviegut). + +### Organization owners + +Organization owners hold administrative access to every repository in the +`cimug-org` organization, independent of the project roles above. This access sits +above the repository's rulesets: an owner can bypass branch and tag protections, +and can modify or remove them. **The owner set is therefore the project's effective +trust boundary**, and no repository setting can constrain it. + +This is stated plainly because a governance document that implied otherwise would +be misleading. The protections described here govern contributors, committers, and +maintainers. They do not durably constrain organization owners, who are able to +edit the protections themselves. + +Current organization owners: + +- Todd Viegut (@tviegut), also lead maintainer +- Jesse Grey (@jarthurgrey) + +An organization owner may belong to a project team for notification and mention +routing. Team membership confers no additional permission on an owner, who already +holds administrative access by virtue of ownership. + +## How decisions are made + +Most decisions are made informally, in the open, on the relevant issue or pull +request. Consensus among maintainers is the norm, and it is usually reached +without anyone needing to call it a decision. + +Where consensus does not emerge: + +- **Technical questions** are settled by the lead maintainer, after the arguments + have been made in public and considered. +- **Questions of project scope, licensing, or governance** are referred to the + UCAIug. + +Decisions that change how CIMTool behaves for existing users, that alter +generated artifacts, or that affect conformance with an IEC standard are +discussed on a public issue before implementation. This is not negotiable, and it +applies to maintainers as much as to outside contributors. + +Nothing in this document creates an entitlement to have a contribution accepted. +Maintainers may decline a change that is well-written, well-tested, and correct, +if it does not serve the project. + +## Becoming a committer or a maintainer + +There is no application process. Committers and maintainers are invited, by +existing maintainers, on the basis of a sustained record of good judgment: +contributions that were correct, review comments that were useful, and conduct +that was consistent with this project's standards. + +Committer status is the ordinary first step. Maintainer status, which carries +merge authority, follows only after a committer has demonstrated sound judgment +in review as well as in code. + +Write access to a repository whose artifacts are deployed in production systems is +a security decision as much as a recognition of merit. It will not be granted +casually, and no contributor should read a delay as a judgment on the quality of +their work. + +An invitation to either role requires the assent of the lead maintainer. Where more +than one maintainer is in post, the maintainers are consulted and their agreement is +sought. + +## Stepping down and removal + +Maintainers and committers who are no longer active may be moved to emeritus +status, retaining credit for their contributions and relinquishing write access. +This is administrative housekeeping rather than a demotion, and it reflects the +security posture above rather than any judgment of the person. A dormant account +holding write access to a repository whose artifacts are deployed in production +systems is a standing risk, and one that goes unnoticed precisely because the +account is not in use. + +No fixed period of inactivity triggers this. Access is reviewed periodically, and +emeritus status is applied at the maintainers' discretion. + +A maintainer or committer may be removed for a sustained violation of the Code of +Conduct, for conduct that endangers the project's users, or by decision of the +UCAIug. + +## Releases + +CIMTool follows the branching and release model described in +[CONTRIBUTING.md](CONTRIBUTING.md). The lead maintainer decides when a release +branch is cut, when a release candidate is promoted, and when a release is +published and tagged. + +Release artifacts are signed. The signing credentials are held by the lead +maintainer and are never exposed to continuous integration triggered by an +untrusted pull request. + +## Amending this document + +Changes to this document are proposed by pull request and require the agreement +of the maintainers. Changes touching the UCAIug's stewardship of the project +require the UCAIug's agreement. diff --git a/.github/ISSUE_TEMPLATE/cimtool-bug-report.md b/.github/ISSUE_TEMPLATE/cimtool-bug-report.md index d7f63c88..9d82bc77 100644 --- a/.github/ISSUE_TEMPLATE/cimtool-bug-report.md +++ b/.github/ISSUE_TEMPLATE/cimtool-bug-report.md @@ -7,6 +7,14 @@ assignees: '' --- +> [!CAUTION] +> **Do not use this template to report a security vulnerability.** +> Filing a vulnerability here discloses it publicly, to everyone, before a fix +> exists. CIMTool runs in production systems, and their operators would learn of the +> problem at the same moment an attacker does. +> Report it privately instead: [open a security advisory](https://github.com/cimug-org/CIMTool/security/advisories/new). +> See [SECURITY.md](https://github.com/cimug-org/CIMTool/blob/master/SECURITY.md). + ### Describe the defect: A clear and concise description of what the defect is. This should include a high level description of what you were trying to do that produced the issue. (e.g. "While creating a new profile I selected the ...") diff --git a/.github/ISSUE_TEMPLATE/cimtool-feature-or-enhancement-request.md b/.github/ISSUE_TEMPLATE/cimtool-feature-or-enhancement-request.md index a4c6fe4f..bee596b0 100644 --- a/.github/ISSUE_TEMPLATE/cimtool-feature-or-enhancement-request.md +++ b/.github/ISSUE_TEMPLATE/cimtool-feature-or-enhancement-request.md @@ -1,7 +1,7 @@ --- name: CIMTool Feature or Enhancement Request about: Suggest an idea for CIMTool -title: "[ENHANCEMENT]" +title: "[ENHANCEMENT] " labels: enhancement assignees: '' diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..abfe4c3d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: false + +contact_links: + - name: Report a security vulnerability + url: https://github.com/cimug-org/CIMTool/security/advisories/new + about: Do NOT open a public issue. Public disclosure exposes every CIMTool user before a fix exists. Report vulnerabilities privately here. + + - name: Ask a question or discuss an idea + url: https://github.com/cimug-org/CIMTool/discussions + about: For usage questions, profiling help, and general discussion. Not for defects or feature requests. + + - name: Read the contributing guidelines + url: https://github.com/cimug-org/CIMTool/blob/master/CONTRIBUTING.md + about: Branch naming, commit conventions, and how to submit a pull request. diff --git a/.github/ISSUE_TEMPLATE/documentation-needed.md b/.github/ISSUE_TEMPLATE/documentation-needed.md index 3de6b796..4f8ffe5f 100644 --- a/.github/ISSUE_TEMPLATE/documentation-needed.md +++ b/.github/ISSUE_TEMPLATE/documentation-needed.md @@ -1,7 +1,7 @@ --- name: Documentation Needed about: Documentation updates or recommendations -title: "[DOCUMENTATION]" +title: "[DOCUMENTATION] " labels: documentation assignees: '' diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 00000000..613a816d --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,111 @@ +# Security Policy + +CIMTool is used in production by organizations whose systems matter. A +vulnerability in this project, or in the dependencies it ships, does not stay +inside this project. We take reports seriously and we ask that you handle them +accordingly. + +## Reporting a vulnerability + +**Do not open a public GitHub issue.** Doing so discloses the vulnerability to +every CIMTool user simultaneously, before a fix exists. + +Report privately using +[GitHub's private vulnerability reporting](https://github.com/cimug-org/CIMTool/security/advisories/new). +This opens a confidential thread visible to you and to the project's maintainers +and committers, and not to the public. It is the preferred channel, and it lets us +prepare a fix and a security advisory in the same place. + +If you are unable to use GitHub, email +[cimtool-security@ucaiug.org](mailto:cimtool-security@ucaiug.org). + +## What to include + +The more of this you can provide, the faster we can respond: + +- The CIMTool release affected, as it appears in the About dialog + (e.g. `CIMTool 2.3.0`). +- The component involved: the Eclipse plugin, `cimtool-cli`, a bundled + third-party library, an XSLT builder, or the build and signing pipeline. +- A description of the vulnerability and its impact. +- Steps to reproduce, or a proof of concept. +- Any CVE identifier, if the issue originates in a dependency. +- Whether you intend to disclose publicly, and on what timeline. + +## Scope + +In scope: + +- The CIMTool Eclipse plugin suite and all sub-projects in this repository. +- Third-party libraries vendored into a CIMTool release, where the way CIMTool + configures or invokes them exposes the vulnerability. +- The release artifacts themselves, including packaging and code signing. + +Out of scope: + +- Vulnerabilities in Eclipse, the JRE, or Enterprise Architect. Report those + upstream. If CIMTool's configuration makes an upstream vulnerability + exploitable in a way it otherwise would not be, that is in scope and we want + to hear about it. +- Vulnerabilities in a dependency that CIMTool does not ship or does not reach. +- Social engineering, physical access, and denial of service against project + infrastructure hosted by GitHub. + +## What to expect + +- **Acknowledgement** within ten business days. +- **An initial assessment**, including whether we agree it is a vulnerability and + our view of its severity, within fifteen business days. +- **Ongoing contact** through the private advisory thread while a fix is prepared. +- **Credit** in the published advisory and the release notes, unless you ask to + remain anonymous. + +CIMTool is maintained by a small team. We will tell you honestly if a fix will +take time, rather than letting a report go quiet. + +## Coordinated disclosure + +We ask that you give us a reasonable opportunity to release a fix before +disclosing publicly. Ninety days from acknowledgement is a customary window and +one we will work within. + +If a vulnerability is already being exploited, or is already public, tell us and +we will move accordingly. + +We will publish a GitHub Security Advisory when a fix is released, and reference +it in the release notes. + +## Supported versions + +Security fixes are applied to the current development branch and delivered in the +next CIMTool release. **Upgrading to that release is the supported remedy.** We +do not maintain parallel patch lines, and users are asked to plan for upgrade +rather than to expect a fix on the release they are running. + +Backporting is possible but discretionary. Where the maintainers judge, after +review, that the severity of a vulnerability and the practical difficulty of +upgrading together warrant it, a fix may be backported to an earlier release. +This is decided case by case on the merits of the specific vulnerability, and +nothing in this policy should be read as a commitment to do so. + +**Where backporting is undertaken, 2.3.0 is the earliest release that will be +considered.** Releases prior to 2.3.0 are unsupported and will not receive +security fixes under any circumstances. + +| Release | Position | +| --- | --- | +| Current release | Receives security fixes. Upgrade here. | +| 2.3.0 through the release preceding the current one | Eligible for backporting at the maintainers' discretion, following review of the specific vulnerability. | +| Prior to 2.3.0 | Unsupported. No security fixes. | + +Utilities operating on a change-controlled release cycle who cannot upgrade +within a reasonable period are encouraged to say so in the private advisory +thread. That context informs the backporting decision, though it does not +determine it. + +## No bug bounty + +CIMTool is an open-source project under the stewardship of the +[UCA International Users Group](https://cimug.ucaiug.org/). It is distributed +free of charge and generates no revenue, and we are not able to offer monetary +rewards. We are able to offer credit, and our thanks. diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 00000000..cb0477dc --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,88 @@ +# Getting Help with CIMTool + +CIMTool is maintained by a small team of sponsored and volunteer contributors, +with further contributions from the wider CIM community. Directing your question +to the right place gets you a faster answer and keeps the issue tracker usable +for the defects and enhancements it exists to track. + +## Start with the documentation + +Most questions are answered in one of these: + +- **[CIMTool website](https://cimtool.ucaiug.io/)** covers installation, setup, + profiling workflow, and the how-to guides. Start here. +- **[CIMTool Builders Library](https://cimtool-builders.ucaiug.io/)** documents + every XSLT builder that ships with CIMTool, along with community-contributed + builders and instructions for importing your own. +- **[Release notes](https://cimtool.ucaiug.io/release-notes/)** describe what + changed in each release, which is often where an unexpected behavior turns out + to be an intentional one. +- **CIMTool's built-in help**, available from the Eclipse Help menu. + +## Ask a question + +For usage questions, profiling advice, schema questions, and anything beginning +"how do I", use +[GitHub Discussions](https://github.com/cimug-org/CIMTool/discussions). + +Discussions are the right place for: + +- How to model something in a profile. +- Why a builder produces the output it does. +- Whether CIMTool supports a particular CIM schema or standard. +- Ideas you would like to talk through before opening an enhancement request. +- Sharing a builder, a workflow, or a worked example with the community. + +When you ask, include the CIMTool release you are running, the CIM schema you +are profiling against, and what you have already tried. A question that can be +answered without a follow-up round trip usually is. + +## Open an issue + +[Open an issue](https://github.com/cimug-org/CIMTool/issues/new/choose) when you +have identified something specific and actionable: + +- A **defect**: CIMTool does something other than what it should. +- An **enhancement**: CIMTool should do something it does not. +- A **documentation gap**: something is missing, wrong, or unclear. + +Search the existing issues first. Please do not use the issue tracker for usage +questions; they will be moved to Discussions. + +## Report a security vulnerability + +**Never in a public issue.** See [SECURITY.md](SECURITY.md). + +## Contribute a fix + +See [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming, commit conventions, and +how to open a pull request. + +## Who develops CIMTool + +CIMTool is an open-source project of the +[UCA International Users Group (UCAIug)](https://cimug.ucaiug.org/), which owns +the project and sets the policies under which it operates. + +**Emerson/AspenTech is the official corporate sponsor of CIMTool** and develops +the tool on behalf of the UCA CIM Users Group. Sponsorship funds development; it +does not confer ownership, and it does not make CIMTool a commercial product. + +Contributions from the wider CIM community are welcome and are reviewed on their +technical merits. See [CONTRIBUTING.md](CONTRIBUTING.md). + +## What to expect + +CIMTool is distributed free of charge under an open-source license. It carries no +warranty, no service level agreement, and no commercial support offering. Neither +the UCAIug nor Emerson/AspenTech undertakes to answer support requests within any +particular period. + +Maintainers and community members answer questions when they are able. A +well-formed question with a reproducible example is far more likely to get a +prompt answer than one that requires the reader to guess at context. + +If your organization depends on CIMTool and needs assurances beyond this, the +mechanism available is to contribute: developer time, testing against your +schemas, documentation, or builders returned to the community. Discuss it with +the [UCA International Users Group](https://cimug.ucaiug.org/). diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 455c241e..11a53628 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,12 +3,14 @@ on: push: branches: - master +permissions: + contents: write jobs: deploy: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-python@v2 + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 with: python-version: 3.x - run: pip install mkdocs-material diff --git a/README.md b/README.md index 338e9d20..a8b585e2 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ [![image](docs/logos/project-supporter-aspentech-logo.gif)](https://www.aspentech.com/en/products/suites/digital-grid-management) -AspenTech serves at the official corporate sponsor supporting the development of CIMTool on behalf of the UCAIug. +AspenTech serves as the official corporate sponsor supporting the development of CIMTool on behalf of the UCAIug. ## CIMTool Discussion Forums -The CIMTool [Google Group](https://groups.google.com/g/cimtool) is no longer actively monitored and has been retained only for archival purposes. Please post all questions, suggestions, and/or comments directly to the new [CIMTool Discussions](https://github.com/ucaiug/CIMTool/discussions) board for this repository. +The CIMTool [Google Group](https://groups.google.com/g/cimtool) is no longer actively monitored and has been retained only for archival purposes. Please post all questions, suggestions, and/or comments directly to the new [CIMTool Discussions](https://github.com/cimug-org/CIMTool/discussions) board for this repository. ## Using CIMTool with Enterprise Architect @@ -32,6 +32,8 @@ For further details on how to use CIMTool to create and edit profiles based on t Note that these instructions are purely for those interested in participating in the development of **CIMTool**. They do not describe standard use of the tool for creating profiles. + Before opening your first pull request, please read the [contributing guidelines](CONTRIBUTING.md). They describe the branching model, commit conventions, and how contributions are reviewed. See also the [Code of Conduct](CODE_OF_CONDUCT.md) and [project governance](GOVERNANCE.md). + ## Product Roadmap The CIMTool public roadmap is maintained on GitHub Projects. View the current release plan and backlog at [CIMTool Roadmap](https://github.com/orgs/cimug-org/projects/17). @@ -40,13 +42,17 @@ The CIMTool public roadmap is maintained on GitHub Projects. View the current re - 2.3.0 - - The latest release is available here on GitHub at [CIMTool-2.3.0](https://github.com/ucaiug/CIMTool/releases) and is delivered as a ZIP file. Releases are also made available in the CIMug [tools download folder](https://cimug.ucaiug.org/Standards%20Artifacts/Forms/AllItems.aspx?RootFolder=%2FStandards%20Artifacts%2FUCA%20TF%20Tools&FolderCTID=0x0120001062F2F1DF27704DBB748ABBDC3B3AA2&View=%7BFEBD8EE1%2D6B40%2D42F6%2DB228%2DCCF131291FBE%7D) on the UCAIug website. + - The latest release is available here on GitHub at [CIMTool-2.3.0](https://github.com/cimug-org/CIMTool/releases/tag/2.3.0) and is delivered as a ZIP file. Releases are also made available in the CIMug [tools download folder](https://cimug.ucaiug.org/Standards%20Artifacts/Forms/AllItems.aspx?RootFolder=%2FStandards%20Artifacts%2FUCA%20TF%20Tools&FolderCTID=0x0120001062F2F1DF27704DBB748ABBDC3B3AA2&View=%7BFEBD8EE1%2D6B40%2D42F6%2DB228%2DCCF131291FBE%7D) on the UCAIug website. - Information on features and fixes for the release can be found [here](https://cimtool.ucaiug.io/release-notes). ## Installation & Setup For instructions on installation and setup of **CIMTool** see [CIMTool Installation & Setup](https://cimtool.ucaiug.io/getting-started/). +## Getting Help + +For usage questions, profiling advice, and general discussion, see [SUPPORT.md](SUPPORT.md), which describes where to ask and what to expect. + ## Security Please do not report security vulnerabilities in public issues. See [SECURITY.md](SECURITY.md) for how to report them privately.