doctrine-website
doctrine-website copied to clipboard
doctrine
Things I wish I had known as a new contributor
... to save my own and my fellow reviewers' time. It's not about the codebase itself, but the conventions and processes around it.
-
Which branch to base a PR on? #473
- Rather obvious for bug fix vs. feature addition
- But what about...
- Docblock fixups
- Psalm/type hint improvements
- Small refactorings like method extractions?
-
How to deal with all the checks and tools? #481
- How to have CS issues fixed automatically
- How to run
psalm,phpcbf,phpcs, ... - What to do when "Codecov" complains about coverage?
-
Dealing with Psalm errors #481
- When to update the baseline file, what to add, what to remove?
- When to add exceptions to
psalm.xml? When to use@psalm-suppress?
-
Rebase and squash your commits periodically?
- ORM maintainers are not going to do squash-merges, right?
-
Write good commit messages for single commits vs. keeping the PR initial comment up-to-date?
-
When and how to add deprecations? #482
- How to add deprecations, technically (does an
@deprecatedannotation suffice, do I need code triggering a notice, ...) - Only add deprecations in upcoming feature release branches, right?
- Where/when/how to provide the code that shall be effective on the next major version?
- How to add deprecations, technically (does an
-
How and when to maintain the
UPGRADING.mdfile -
Getting PRs reviewed #484
- Do checks have to be all green before people will have a look at my code?
- When shall I use "draft" PRs and what (not) to expect from them?
- How can I indicate that I need early guidance and/or basic approval, before putting too much effort into detailed clean-ups?
This is not to blame anyone for not providing the necessary instructions and documentation, at least not in places where I would have to stumble across. Rather I am trying to document my observations as long as they are fresh and clear, hoping that the list can serve as starting pointers for future improvements.
👇 Anything missing on the list? Feel free to add your observations.
It's going to be hard for us to agree on everything, so I will create several PRs instead of a big one. Transferring the issue since it isn't ORM-specific.
