Development Policies and Procedures - pc2ccs/pc2v9 GitHub Wiki

This page presents a list of policies and practices that should be followed by all PC2V9 contributors. Note that since we believe in the policy of eating your own dog food, these policies and practices apply equally to the PC2 Development Team (the maintainers of the PC2 Git repo) as well as to contributing developers.

Development Policies

  • All development work must be done off a fork.

  • Every issue (bug fix or new feature) must be done on its own separate issue branch.

  • Test issue fixes against the current develop head before submitting a PR.

  • Except for the case of sync'ing your fork with the current PC2v9 master repo, do not push anything other than a specific issue branch to your fork.

  • Do not use features from a Java version beyond version 1.8 [1]

Approval Policies

  • Only changes submitted via a GitHub Pull Request will be considered for merging into the PC² code stream.

  • PR's are always (only) merged to the develop branch. (The only time things are merged to the master branch is when a new "Release Candidate" is being created.)

  • PR's require review and approval by at least two committers in order to be merged. (A committer is a person who has write-access to the PC2 Git repository and thus can "commit" changes to it.) Committers who review a PR and believe it should be approved as-is should explicitly state in their review a note to the effect "I approve this PR".

  • PR's may be returned by reviewers to the submitter with requests for changes; in that case it is incumbent upon the submitter to resolve whatever issues are noted in order to obtain approval from at least two committers.

  • For PR's submitted by committers, the following additional rules apply:

    • The PR submitter, who is implicitly assumed to approve, constitutes one of the two required approving committers; hence it requires at least one other committer to approve merging such a PR.
    • Just as with PR's submitted by other developers, a PR submitted by a committer which receives reviews that request changes makes it incumbent upon the submitter to work to resolve the issues identified in the review to the point where at least one other committer agrees to approve.
    • A PR which has been submitted by a committer and which has zero reviews after 3 weeks may be self-approved by the submitter for merging to develop.  

Typical Development Procedures

The above policies lead to a set of common procedures and practices, which are outlined below.

  • Practice 1: do not merge any branch into develop or master on a fork, or into develop or master in a local repo where it can be pushed to a fork. This can cause the situation where multiple issues in a working branch get pushed upstream, leading to PRs containing multiple issues (which will be rejected).

  • Practice 2: do not push anything up to a fork except an issue-specific "topic" ("feature") branch. Again, this can cause the situation where multiple issues are contained in a single PR.

  • Practice 3: Test locally against the current develop branch. This refers to testing which is done after the fix or new feature is deemed "working" in its own right -- it is then necessary to insure that it is compatible with any changes which may have been made to the PC2V9 main repo in the interim. To accomplish testing against the current PC2V9 repo, it is necessary to bring down any changes in that repo, rebase your code on top of those changes, and then verify the code still works (or fix any problems). See Development Flow for the steps involved in doing this testing.

  • Practice 4: Submit an issue-specific PR for the issue. Every issue requires its own issue-specific PR; do not submit PR's containing code fixes related to things not covered in the specific PC2v9 GitHub Issue identified in the issue branch. See Development Flow for specific steps on submitting PRs; see Guidelines for Submitting Pull Requests for additional information.

See Also

[1] There is a reason we restrict development to using only features supported by older versions of Java: because it is very typical that our users are running on such older versions. We want to avoid a scenario where users have to upgrade their Java installation just to use PC2. We regularly re-evaluate what the "supported Java version" for PC2 should be, and update it when it seems clear that it's reasonable to require ALL users to upgrade to that version. (If you believe the Java version mentioned on this wiki page is out of date with respect to the current Java version supported by PC2, please let us know.)