Developers

Contact Us

Direct any questions to irc.freenode.net #mpos-dev.

Git Configuration

Line endings

In .gitconfig, core.autocrlf needs to be set to input, like so:

git config --global core.autocrlf input

This will convert line endings to LF when committing (the standard) and back to whatever the local system uses when pulling. Also, GitHub's help page are incorrect, it is actually correct to use input on all OSes.

To prevent this from being the top-level configuration for git, just remove the --global option. If this method is chosen it must be set on all copies mpos repositories.

Forking

See here for help. Once forked, add a remote repository pointing to the primary upstream repository with git remote add upstream https://github.com/MPOS/php-mpos.git. To keep in-sync with the changes made upstream use git pull upstream master, this continually will sync copies.

Only after pulling upstream should the fork be pushed to and a pull request opened. This is to prevents extra quality control from having to be performed, and an easier changelog to be read.

When deleting the fork, all pending pull requests must be deleted, closed, or merged. GitHub will not accept it if it has not been done.

Conflicting merge commits

When merging a conflicting branch with upstream, do not remove the automatically-inserted list (in the commit message) of conflicting files.

Pull requests

A pull request (PR) is the primary way to push changes upstream. Requests from a fork that is not up-to-date with upstream will not be accepted, do not send them unless they are fully up-to-date. This will prevent rogue merges where one branch breaks something upstream due to conflict, or (more often) in some other obtuse, generally unexplainable fashion. For help sending a PR, see here.

Merging a PR will only be allowed when it is described adequately and follows the design and coding style of the repository.

Commits/PRs (typically) not merged:

• With commit message(s) "Edited ... via GitHub": These kinds of commits are explicitly refused due to not being able to tell what the commit does in commands like git log (without consulting the diff). There is a text box for the commit message below the edit box, or use a proper git client and make proper commits.
• With no or inadequate descriptions: Sometimes they may pass by being descriptive enough in commit messages, but it is best to properly describe a PR. Even a summary of the commits will suffice, though this does not exclude from writing proper commit messages in the first place.

A proper commit or PR will:

• Reference any issues (#XYZ in the commit or PR description, where XYZ is the issue number) that have been fixed (or for other reasons).
• Aptly describe what has been fixed/changed rather than, for example, "ponies weren't working right", where "ponies weren't working right" has presumably been 'fixed'.

A PR's description is best kept as a summary of the commits therein. Rule of thumb is:

• PR descriptions are verbosely descriptive summarisations.
• PR titles are a conciser version of the description.

To prevent an active PR from picking up all the commits to a master branch, work should be done in a separate branch and only merged back to the master when the PR is closed (or to include the commits from the branch in the PR). This can also be prevented by setting the PR's range to end at the last commit made, though in that setup it is impossible to put any more commits in the PR since the range stops at a specific commit rather than the entire master branch.