Contributor guidelines / templates
How to Engage, Contribute, and Give Feedback
- Some of the best ways to contribute are to try things out, file issues, join in design conversations, and make pull-requests.
- Review current outstanding issues before submitting new ones. If an issue is important to you, give it the
👍 reaction! Reactions help us prioritize outstanding issues for future milestones, comments such as "I need this!!" do nothing but bother the participants and clutter the conversation. - Not everyone is a master of the English language. Since project development is done primarily in English, using simple wording in both issues and source code commentary helps non-native contributors better understand them; Common technical jargon is OK!
- We want the PageDriver community to be as welcoming as possible to everyone. Please try to use inclusive, gender neutral language and be polite to each other.
- Join our Discord server community.
Getting Started on GitLab
- Review our label descriptions to help navigate issues. Hovering over labels on desktop also reveals descriptions.
- Milestones (eg. %Library v1) don't exclusively cover the domain they are named after, it's simply their primary focus.
- When viewing issues, we recommend the 'Show comments only' option for the activity feed.
- GitLab power user? Check out the StyleLab repository!
Non-member submission labelling
- All submissions MUST begin with ? label
- All bug reports MUST begin as bug::1: Unconfirmed
🔍
Team specific labels
-
CIU
⏳ for issues waiting for, or relating to features below the project's Caniuse.com threshold. Eventually this will be automated. - All scoped 'bug' labels past bug::1: Unconfirmed
🔍 step. - Leads/caretakers only
- + denote an enhancement
- ! denote critical and immediate priority
- when::Now when::Next when::Future are informal anticipated priority for milestone assignment. Don't apply 'when' to ? issues. 'Flow' label progress is unrelated to 'when' label state (an issue that becomes f::2: Active doesn't change 'Next' to 'Now').
- reference to denote ... a reference topic. Kind of a hack but better than splitting community activity between multiple locations ¯\_(ツ)_/¯
- rejected
Advice for leads
- Weights are guesses and optional. From trivial (1) to major projects/reworks (15).
- Example issue belonging in core library
- Better handling of generic types in C::DOM populator.
- Implementation/performance improvements of existing core functionality.
- Items relating to project goals.
Issue guidelines
ALL ISSUES
- MUST have domain scope label, eg. d::Library or d::L+F.
- The
👍 reaction is our official "Me too!" reaction, helping us prioritize outstanding issues. - Repeat above 'engagement' copy in
<!-- -->
or pre-submission notice.
General discussion issue
- MUST have ? and f::1: Discuss labels.
- Apply/remove other topic labels as discussion evolves.
Vulnerability reports
- (UNDECIDED) Non-members CANNOT submit vuln. reports, they must email security@pagedriver.org instead.
- MUST be marked as confidential.
- MUST have security label.
Enhancement/ Feature / Module requests
- MUST have + label
- Project leads will have final say, and either:
- approves the request. Optionally cleaning up description and applying weight, 'flow' and/or 'when' labels.
- or after providing rationale, apply the rejected label and close the issue.
Bug reports
- MUST have a scoped bug label
- Title MUST clearly explain unexpected behaviour, and later re-titled to the broadest scope necessary for ease of discovery.
- 'Missing feature' reports that aren't regressions are 'Enhancement requests' in disguise. If issue is well written/discussed, lead MAY replace 'bug' label with + and edit appropriately. Otherwise, submitter must be made aware to resubmit as a feature request, apply bug::4: Not bug and close issue.
- Reports regarding an intentional development decision or user inexperience (PEBCAK) are not considered bugs. Submitter must be made aware of this. Apply bug::4: Not bug, however before closing the issue, consider the f::4: Document
📑 'flow' scoped label, as this may be a symptom of lacking relevant documentation.
Template
### Reproducing Attach a GIF / link a recording of the issue OR describe process step by step: 1. Step one 2. Step two ...We highly recommend LICEcap for short GIFs.
Consistency
- Is this a consistent behaviour? Yes/No
- If inconsistent, explain why (if known): N/A
- Does this also occur in development mode? Yes/No
- If this worked in a previous release, provide the tag: v#.#.#
Environment
- Release tag: v0.0.1
- Domain label: eg. d::Library
- Edition: ed::Community or ed::Pro
Possible solution
If you believe you know the exact cause of this issue, and have a possible solution, mention it here.
Please, no "me too" comments
When contributing to the issue tracker, please don't post comments like these:
+1
or
👍
or
Me too.
or
I too would like to see this issue fixed.
or
When is this issue going to be fixed?
Such comments don't help fix issues. In fact, they make it harder by cluttering the discussion. The project librarians will delete such comments as a matter of procedure (please don't be offended if we delete yours).
Instead of commenting, add a
Of course, please do comment if your "me too" comment includes information that might help resolve the issue. This includes reports like this:
This issue also affects me on Safari Technology Preview v146 when switching pages.
(Although there's no need to make such a comment if an identical comment already exists.)