Skip to content

Commit

Permalink
docs(pr_template): various fixes and comment updates (#2156)
Browse files Browse the repository at this point in the history
  • Loading branch information
@wdhdev
wdhdev authored Sep 16, 2024
1 parent 4bccd32 commit b58c63e
Showing 1 changed file with 43 additions and 58 deletions.
101 changes: 43 additions & 58 deletions .github/pull_request_template.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
Public Suffix List (PSL) Pull Request (PR) Template
====
# Public Suffix List (PSL) Submission

Each PSL PR needs to have a description, rationale, indication of DNS validation and syntax checking, as well as a number of acknowledgements from the submitter. This template must be included with each PR, and the submitting party MUST provide responses to all of the elements in order to be considered.
<!--
Each PSL PR needs to have a description, rationale, indication of DNS validation and syntax checking, as well as a number of acknowledgements from the submitter. This template must be included with each PR, and the submitting party MUST provide responses to all of the elements in order to be considered.
-->

<!-- #### READ THIS FIRST ####
Expand All @@ -10,27 +11,28 @@ https://github.com/publicsuffix/list/wiki/Guidelines#submit-the-change
Also, read them again, as many skip that part and
get confused about why their PR is delayed or does
not get accepted when theirs didn't follow them.
not get accepted when their submission didn't follow them.
A recent PR using the current template is
https://github.com/publicsuffix/list/pull/1591, although
the organization and description were not as substantial
as desired, which required maintainers time to visit the
requestors website to further research.
requestors website to further research.
Having more robust org/desc improves the PR processing
pace due to the extra cycles not lost to research.
pace due to the extra cycles not being lost to research.
For an example of what an excellent description in a PR looks like
see https://github.com/publicsuffix/list/pull/615,
although that example uses an earlier template.
-->

### Checklist of required steps

* [ ] Description of Organization
* [ ] Robust Reason for PSL Inclusion
* [ ] DNS verification via dig
* [ ] Run Syntax Checker (make test)
* [ ] Run Syntax Checker (`make test`)

* [ ] Each domain listed in the PRIVATE section has and shall maintain at least two years remaining on registration, and we shall keep the \_PSL txt record in place in the respective zone(s) in the affected section
* [ ] Each domain listed in the PRIVATE section has and shall maintain at least two years remaining on registration, and we shall keep the `_psl` TXT record in place in the respective zone(s).

__Submitter affirms the following:__
<!--
Expand All @@ -44,10 +46,11 @@ your domain(s) directly with that third-party, and it is inappropriate
to submit entries to the PSL as a means to work around those limits or
restrictions.
-->
* [ ] We are listing *any* third-party limits that we seek to work around in our rationale such as those between IOS 14.5+ and Facebook (see [Issue #1245](https://github.com/publicsuffix/list/issues/1245) as a well-documented example)
- [Cloudflare](https://developers.cloudflare.com/learning-paths/get-started/add-domain-to-cf/add-site/)
- [Letsencrypt](https://letsencrypt.org/docs/rate-limits/)
- <UPDATE THIS LIST WITH YOUR LIMITATIONS! REMOVE ENTRIES WHICH DO NOT APPLY! REMOVE THIS LINE!>

* [ ] We are listing *any* third-party limits that we seek to work around in our rationale such as those between IOS 14.5+ and Facebook (see [Issue #1245](https://github.com/publicsuffix/list/issues/1245) as a well-documented example)
- [Cloudflare](https://developers.cloudflare.com/learning-paths/get-started/add-domain-to-cf/add-site/)
- [Let's Encrypt](https://letsencrypt.org/docs/rate-limits/)
- MAKE SURE UPDATE THE FOLLOWING LIST WITH YOUR LIMITATIONS! REMOVE ENTRIES WHICH DO NOT APPLY AS WELL AS REMOVING THIS LINE!

<!--
The purpose of the question above is to expose limit workarounds.
Expand All @@ -65,38 +68,38 @@ requesting party that they are not attempting to bypass rate limits through
the PR.
-->

* [ ] This request was _not_ submitted with the objective of working around other third-party limits
* [ ] This request was _not_ submitted with the objective of working around other third-party limits.

<!--
Submitter will maintain domains in good standing or may lose section.
The ongoing trust of the PSL requires it to be free of outdated or problematic entries. In making this pull request, there is a commitment by the submitter that they are going to review and maintain their relevant section. By submitting an entry, the requestor acknowledges that their entry and section may be removed if the domain does not maintain the respective _PSL entries in DNS, any domain(s) within their section fail to resolve in DNS, the domain does not get renewed, expires or is otherwise unreachable. Submitter further identifies that it is their responsibility to review their submitted section within the PSL, submitting updates or removals as their domain(s) may change over time. It is also the responsibility of the submitter to provide (and keep up to date) a reachable email address within the section, and to maintain that address as it may change over time, so that they receive notices.
The ongoing trust of the PSL requires it to be free of outdated or problematic entries. In making this pull request, there is a commitment by the submitter that they are going to review and maintain their relevant section. By submitting an entry, the requestor acknowledges that their entry and section may be removed if the domain does not maintain the respective _psl entries in DNS, any domain(s) within their section fail to resolve in DNS, the domain does not get renewed, expires or is otherwise unreachable. The submitter further identifies that it is their responsibility to review their submitted section within the PSL, submitting updates or removals as their domain(s) may change over time. It is also the responsibility of the submitter to provide (and keep up to date) a reachable email address within the section, and to maintain that address as it may change over time, so that they receive notices.
-->

* [ ] The submitter acknowledges that it is their responsibility to maintain the domains within their section. This includes removing names which are no longer used, retaining the _psl DNS entry, responding to e-mails to the supplied address. Failure to maintain entries may result in removal of individual entries or the entire section.
* [ ] The submitter acknowledges that it is their responsibility to maintain the domains within their section. This includes removing names which are no longer used, retaining the _psl DNS entry, and responding to e-mails to the supplied address. Failure to maintain entries may result in removal of individual entries or the entire section.

<!--
The guidelines describe which section to place the entry, what the
order of commented org placement, order of sorting of entries.
(hint: TLD then SLD, Ascending sort) Although it seems pedantic,
(hint: TLD then SLD, ascending sorting) Although it seems pedantic,
the sorting and formatting rules help ensure all of the automation
that uses the PSL operates correctly. Typically both are solved or
that uses the PSL operates correctly. Typically both are solved or
neither.
-->

* [ ] The [Guidelines](https://github.com/publicsuffix/list/wiki/Guidelines) were carefully _read_ and _understood_, and this request conforms
* [ ] The submission follows the [guidelines](https://github.com/publicsuffix/list/wiki/Format) on formatting and sorting
* [ ] The [Guidelines](https://github.com/publicsuffix/list/wiki/Guidelines) were carefully _read_ and _understood_, and this request conforms to them.
* [ ] The submission follows the [guidelines](https://github.com/publicsuffix/list/wiki/Format) on formatting and sorting.

<!--
Sorting and formatting of the entries is outlined in the guidelines
and non-conforming requests are one of the largest sources of delay,
so getting this right initially will aid successfully having it
proceed. Miss-located entries and trailing spaces should be avoided.
proceed. Mislocated entries and trailing spaces should be avoided.
-->

---

For Private section requests that are submitting entries for domains that match their organization website's primary domain, please understand that this can have impacts that may not match the desired outcome and take a long time to rollback, if at all.
For PRIVATE section requests that are submitting entries for domains that match their organization website's primary domain, please understand that this can have impacts that may not match the desired outcome and take a long time to rollback, if at all.

To ensure that requested changes are entirely intentional, make sure that you read the affectation and propagation expectations, that you understand them, and confirm this understanding.

Expand All @@ -108,9 +111,9 @@ guidelines. Your request could very likely alter the cookie and
certificate (as well as other) behaviours on your core domain name in
ways that could be problematic for your business.
Rollback is really not predictable, as those who use or incorporate
Rollbacks are really not predictable, as those who use or incorporate
the PSL do what they do, and when. It is not within the PSL volunteers'
control to do anything about that.
control to do anything about that.
The volunteers are busy with new requests, and rollbacks are lowest
priority, so if something gets broken by your PR, it will potentially
Expand All @@ -119,7 +122,7 @@ stay that way for an indefinite period of time (typically long).

(Link: [about propagation/expectations](https://github.com/publicsuffix/list/wiki/Guidelines#appropriate-expectations-on-derivative-propagation-use-or-inclusion))

* [ ] *Yes, I understand*. I could break my organization's website cookies etc. and the rollback timing, etc is acceptable. *Proceed*.
* [ ] *Yes, I understand*. I could break my organization's website cookies and cause other issues, and the rollback timing is acceptable. *Proceed anyways*.
---


Expand All @@ -133,18 +136,16 @@ Example:
-->

Description of Organization
====

## Description of Organization
<!--
PROVIDE AT LEAST THREE SENTENCES (the more the better) but
Provide at least 3 sentences (the more the better) but
avoid the promotional stuff about how wonderful it is, and
please do not copy and paste the mission statement or
elevator pitch from your org's website.
Also tell us who you (submitter) are and represent (i.e.
individual, non-profit volunteer, engineer at a business)
and what you do (i.e. DynDNS, Hosting, etc), and what your
individual, non-profit volunteer, engineer at a business, etc.)
and what you do (i.e. DynDNS, hosting, etc.), and what your
role is as submitter with respect to the org and the
submission.
Expand All @@ -155,19 +156,14 @@ the submitting org, specifically with context/connection
to this request.
-->

Organization Website:
<!--
Provide the website address of
the Org as a full URL i.e. https://example.com
-->

Reason for PSL Inclusion
====
**Organization Website:**
<!-- Provide the website address of the org as a full URL (i.e. https://example.com) -->

## Reason for PSL Inclusion
<!--
Please tell us why your domain(s) should be listed in the PSL
(i.e. Cookie Security, Let's Encrypt issuance, IOS/Facebook,
Cloudflare etc) and clearly confirm that any private section
Cloudflare, etc.) and clearly confirm that any private section
names hold registration term longer than 2 years and shall
maintain more than 1 year term in order to remain listed.
Expand All @@ -176,23 +172,19 @@ this area to describe how and detail the manner in which you
have first attempted to engage those third parties on the
matter.
Please also include the numbers of any past Issue # or PR #
Please also reference any past issues or PRs
specifically related to this submission or section.
Three or more sentences here that describe the purpose for
which your PR should be included in the PSL. There is no
Provide three or more sentences here that describe the purpose
for which your PR should be included in the PSL. There is no
upper limit, but six paragraphs seems like a rational stop.
-->

Number of users this request is being made to serve:
<!--
Identify if this is current or an estimate.
-->
**Number of users this request is being made to serve:**
<!-- Identify if this is current or an estimate. -->


DNS Verification via dig
=======

## DNS Verification
<!--
For each domain you'd like to add to the list please create
a DNS verification record pointing to your pull request.
Expand All @@ -215,20 +207,13 @@ Note that XXXX is replaced with the number of your pull request.
We ask that you leave this record in place while you want
your entry to remain in the PSL, so that future (TBD)
automation can remove entries where the record is not present.
-->

Results of Syntax Checker (`make test`)
=========

## Results of Syntax Checker (`make test`)
<!--
Please verify that you followed the correct syntax and nothing broke
git clone https://github.com/publicsuffix/list.git
cd list
make test
Simply let us know that you ran the test and those results
Simply let us know that you ran the test and the result of it.
-->


0 comments on commit b58c63e

Please sign in to comment.