From de1ba29a7d98354b2e583d04d63b821550563e81 Mon Sep 17 00:00:00 2001 From: "Stephen Augustus (he/him)" Date: Mon, 2 Jan 2023 23:52:31 -0500 Subject: [PATCH] docs: Update community health files (#56) - DCO: Cleanup text - contributing: Update community health files - Update contributing instructions - Add security policy - Remove CoreOS Code of Conduct - docs: Formatting cleanups Signed-off-by: Stephen Augustus --- .github/settings.yml | 2 +- CONTRIBUTING.md | 61 +++++++++++++++++---------------- DCO | 2 -- README.md | 81 +++++++++++++++++++++++++------------------- SECURITY.md | 12 +++++++ code-of-conduct.md | 63 ---------------------------------- 6 files changed, 90 insertions(+), 131 deletions(-) create mode 100644 SECURITY.md delete mode 100644 code-of-conduct.md diff --git a/.github/settings.yml b/.github/settings.yml index 32973ada..f465bbea 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -5,7 +5,7 @@ repository: name: gh-jira-issue-sync # A short description of the repository that will show up on GitHub - description: A tool for synchronizing issue tracking from GitHub to JIRA + description: A tool for synchronizing issue tracking from GitHub to Jira # A URL with more information about the repository homepage: https://pkg.go.dev/github.com/uwu-tools/gh-jira-issue-sync diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70d08e8d..a0465e7d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,54 +1,59 @@ # How to Contribute -CoreOS projects are [Apache 2.0 licensed](LICENSE) and accept contributions via -GitHub pull requests. This document outlines some of the conventions on -development workflow, commit message formatting, contact points and other -resources to make it easier to get your contribution accepted. +This projects is [Apache 2.0 licensed](/LICENSE) and accept contributions via +pull requests. This document outlines some of the conventions on development +workflow, commit message formatting, contact points and other resources to make +it easier to get your contribution accepted. -## Certificate of Origin +## Developer Certificate of Origin -By contributing to this project you agree to the Developer Certificate of +By contributing to this project, you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the -contribution. See the [DCO](DCO) file for details. +contribution. See the [DCO](/DCO) file for details. -## Email and Chat +## Support -The project currently uses the general CoreOS email list and IRC channel: -- Email: [coreos-dev](https://groups.google.com/forum/#!forum/coreos-dev) -- IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) IRC channel on freenode.org +The project currently uses [GitHub issues](https://github.com/uwu-tools/gh-jira-issue-sync/issues) +to provide support. -Please avoid emailing maintainers found in the MAINTAINERS file directly. They -are very busy and read the mailing lists. +Please avoid emailing maintainers directly as we actively review the issues and +pull requests contained in this repository. -## Reporting a security vulnerability +## Reporting a security vulnerability -Due to their public nature, GitHub and mailing lists are not appropriate places for reporting vulnerabilities. Please refer to CoreOS's [security disclosure][disclosure] process when reporting issues that may be security related. +See [SECURITY.md](/SECURITY.md). ## Getting Started - Fork the repository on GitHub -- Read the [README](README.md) for build and test instructions +- Read the [README](/README.md) for build and test instructions - Play with the project, submit bugs, submit patches! ### Contribution Flow This is a rough outline of what a contributor's workflow looks like: -- Create a topic branch from where you want to base your work (usually master). -- Make commits of logical units. -- Make sure your commit messages are in the proper format (see below). -- Push your changes to a topic branch in your fork of the repository. +- Create a topic/feature branch from where you want to base your work (usually + `main`) +- Make commits of logical units +- Make sure your commit messages are in the proper format (see below) +- Push your changes to a topic/feature branch in your fork of the repository - Make sure the tests pass, and add any new tests as appropriate. -- Submit a pull request to the original repository. +- Submit a pull request to the original repository Thanks for your contributions! ### Coding Style -CoreOS projects written in Go follow a set of style guidelines that we've documented -[here](https://github.com/coreos/docs/tree/master/golang). Please follow them when -working on your contributions. +This project has linters enabled, which run as part of our presubmit checks. + +While we don't currently have our own style guide, we do attempt to adhere to +good examples in other Golang projects, like the Kubernetes SIG Release +[code contribution expectations](https://git.k8s.io/sig-release/CONTRIBUTING.md#coding-style) +and [coding style](https://git.k8s.io/sig-release/CONTRIBUTING.md#coding-style). + +Please follow them when working on your contributions. ### Format of the Commit Message @@ -61,8 +66,6 @@ scripts: add the test-cluster command this uses tmux to setup a test cluster that you can easily kill and start for debugging. - -Fixes #38 ``` The format can be described more formally as follows: @@ -76,9 +79,7 @@ The format can be described more formally as follows: ``` The first line is the subject and should be no longer than 70 characters, the -second line is always blank, and other lines should be wrapped at 80 characters. +second line is always blank, and other lines should be wrapped at 80 +characters. This allows the message to be easier to read on GitHub as well as in various git tools. - - -[disclosure]: https://coreos.com/security/disclosure/ diff --git a/DCO b/DCO index 716561d5..49b8cb05 100644 --- a/DCO +++ b/DCO @@ -2,8 +2,6 @@ Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. diff --git a/README.md b/README.md index b01f9db3..bc3e7471 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,25 @@ -# gh-jira-issue-sync +# [`gh-jira-issue-sync`](https://pkg.go.dev/github.com/uwu-tools/gh-jira-issue-sync) -Issue-sync is a tool for mirroring GitHub issues in JIRA. It grew -out of a desire to maintain a public GitHub repo while tracking private -issues in a JIRA board; rather than require people to keep up with both -sources, we decided to make *one* the single source of truth. Note that -gh-jira-issue-sync works only one way and will **NOT** mirror issues from JIRA to -GitHub. +[![PkgGoDev](https://pkg.go.dev/badge/github.com/uwu-tools/gh-jira-issue-sync)](https://pkg.go.dev/github.com/uwu-tools/gh-jira-issue-sync) +[![Go Report Card](https://goreportcard.com/badge/github.com/uwu-tools/gh-jira-issue-sync)](https://goreportcard.com/report/github.com/uwu-tools/gh-jira-issue-sync) + +`gh-jira-issue-sync` is a tool for mirroring GitHub issues in Jira. It grew out +of a desire to maintain a public GitHub repo while tracking private issues in a +Jira board; rather than require people to keep up with both sources, we decided +to make *one* the single source of truth. + +_Note that `gh-jira-issue-sync` works only one way and will **NOT** mirror +issues from Jira to GitHub._ ## Usage -### JIRA Configuration +### Jira Configuration -To use, first ensure you have a JIRA server with the project you want +To use, first ensure you have a Jira server with the project you want to track on it - it can be a cloud account, or self-hosted. Also make sure you have a user account that can access the project and create issues on it; it's recommended that you create an account specifically -for the issue-sync tool. +for the tool. The following custom fields must be configured AND associated to the appropriate project's screens: @@ -29,35 +33,42 @@ appropriate project's screens: | `github-labels` | Labels | | `github-last-sync` | Date Time Picker | -If you intend to use OAuth with JIRA, you must create an inbound +If you intend to use OAuth with Jira, you must create an inbound application connection and add a public key. Instructions can be found in [OAuth for Rest APIs](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-oauth-authentication/). ### Application Configuration -Arguments to the program may be passed on the command line or in a -JSON configuration file. For the command line arguments, run `gh-jira-issue-sync -help`. The JSON format is a single, flat object, with the argument long +Arguments to the program may be passed on the command line or in a JSON +configuration file. + +For the command line arguments, run: + +```console +gh-jira-issue-sync help +``` + +The JSON format is a single, flat object, with the argument long names as keys. Configuration arguments are as follows: -Name|Value Type|Example Value| Required|Default -----|----------|-------------|---------|------------- -log-level|string|"warn"|false|"info" -github-token|string| |true|null -jira-user|string|"user@jira.example.com"|false|null -jira-pass|string| |false|null -jira-token|string| |false|null -jira-secret|string| |false|null -jira-consumer-key|string| |false|null -jira-private-key-path|string| |false|null -repo-name|string|"coreos/issue-sync"|true|null -jira-uri|string|"https://jira.example.com|true|null -jira-project|string|"SYNC"|true|null -since|string|"2017-07-01T13:45:00-0800"|false|"1970-01-01T00:00:00+0000" -timeout|duration|500ms|false|1m +| Name | Value Type | Example Value | Required | Default | +| --- | --- | --- | --- | --- | +| log-level | string | "warn" | false | "info" | +| github-token | string | | true | null | +| jira-user | string | "user@jira.example.com" | false | null | +| jira-pass | string | | false | null | +| jira-token | string | | false | null | +| jira-secret | string | | false | null | +| jira-consumer-key | string | | false | null | +| jira-private-key-path | string | | false | null | +| repo-name | string | "uwu-tools/gh-jira-issue-sync" | true | null | +| jira-uri | string | "https://jira.example.com" | true | null | +| jira-project | string | "SYNC" | true | null | +| since | string | "2017-07-01T13:45:00-0800" | false | "1970-01-01T00:00:00+0000" | +| timeout | duration | 500ms | false | 1m | ### Configuration Key Descriptions @@ -68,22 +79,22 @@ this value will be discarded. specific user. `jira-user` and `jira-pass` are the username (i.e. email) and password -of the JIRA user which will be authenticated. See `Authentication` for +of the Jira user which will be authenticated. See `Authentication` for more details. `jira-token` and `jira-secret` are OAuth access tokens which will be -used to perform an OAuth connection to JIRA. `jira-consumer-key` and +used to perform an OAuth connection to Jira. `jira-consumer-key` and `jira-private-key-path` are the RSA key used for OAuth. See `Authentication` for more details. `repo-name` is the GitHub repo from which issues will be retrieved. It must be in the form `owner/repo`, for example `uwu-tools/gh-jira-issue-sync`. -`jira-uri` is the base URL of the JIRA instance. If the JIRA instance +`jira-uri` is the base URL of the Jira instance. If the Jira instance lives at a non-root URL, the path must be included. For example, `https://example.com/jira`. -`jira-project` is the key (not the name) of the project in JIRA to +`jira-project` is the key (not the name) of the project in Jira to which the issues will be synchronized. `since` is the cutoff date issue-sync will use when searching for issues @@ -113,10 +124,10 @@ to the current date when the tool is run, as well. ### Authentication If `jira-user` or `jira-pass` are provided, both are required, and the -application will connect to JIRA via Basic Authentication. +application will connect to Jira via Basic Authentication. Otherwise, OAuth will be used. In this case, the `jira-consumer-key`, which is the -name of the RSA public key on the JIRA server, and the +name of the RSA public key on the Jira server, and the `jira-private-key`, which is the path to the RSA private key which matches, must be provided. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..8ed6461a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,12 @@ +# Security Policy + +## Reporting a Vulnerability + +**_Due to their public nature, GitHub issue trackers are not appropriate places +for reporting vulnerabilities._** + +This project uses GitHub's private vulnerability reporting to triage and +remediate potential security issues. + +To learn more about the private vulnerability reporting process, read GitHub's +docs [here](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability). diff --git a/code-of-conduct.md b/code-of-conduct.md deleted file mode 100644 index c0c20dd8..00000000 --- a/code-of-conduct.md +++ /dev/null @@ -1,63 +0,0 @@ -## CoreOS Community Code of Conduct - -### Contributor Code of Conduct - -As contributors and maintainers of this project, and in the interest of -fostering an open and welcoming community, we pledge to respect all people who -contribute through reporting issues, posting feature requests, updating -documentation, submitting pull requests or patches, and other activities. - -We are committed to making participation in this project a harassment-free -experience for everyone, regardless of level of experience, gender, gender -identity and expression, sexual orientation, disability, personal appearance, -body size, race, ethnicity, age, religion, or nationality. - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery -* Personal attacks -* Trolling or insulting/derogatory comments -* Public or private harassment -* Publishing others' private information, such as physical or electronic addresses, without explicit permission -* Other unethical or unprofessional conduct. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct. By adopting this Code of Conduct, -project maintainers commit themselves to fairly and consistently applying these -principles to every aspect of managing this project. Project maintainers who do -not follow or enforce the Code of Conduct may be permanently removed from the -project team. - -This code of conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting a project maintainer, Brandon Philips -, and/or Meghan Schofield -. - -This Code of Conduct is adapted from the Contributor Covenant -(http://contributor-covenant.org), version 1.2.0, available at -http://contributor-covenant.org/version/1/2/0/ - -### CoreOS Events Code of Conduct - -CoreOS events are working conferences intended for professional networking and -collaboration in the CoreOS community. Attendees are expected to behave -according to professional standards and in accordance with their employer’s -policies on appropriate workplace behavior. - -While at CoreOS events or related social networking opportunities, attendees -should not engage in discriminatory or offensive speech or actions including -but not limited to gender, sexuality, race, age, disability, or religion. -Speakers should be especially aware of these concerns. - -CoreOS does not condone any statements by speakers contrary to these standards. -CoreOS reserves the right to deny entrance and/or eject from an event (without -refund) any individual found to be engaging in discriminatory or offensive -speech or actions. - -Please bring any concerns to the immediate attention of designated on-site -staff, Brandon Philips , and/or Meghan Schofield -.