We outline below the workflow we use for developing X-PSI.
You can interact with the X-PSI Team in the public domain on GitHub. We may also be contacted privately at xpsi-team[at]googlegroups.com. Private development between releases is performed in a private repository on BitBucket. We communicate internally in our Slack workspace, in a mixture of private and open channels.
To contribute to this project you can do so whilst being recognised as either a community member or a team member. If you contribute to feature development publicly on GitHub, you may well be invited to be recognised as a team member in the Acknowledgements, and to join the mailing group and our Slack workspace.
Community members can request to join our Slack workspace without being recognised as a team member (or developing features). Community members who are experienced users and are willing to donate some of their time to assisting other X-PSI users (the potential benefits of engaging in such interaction are perhaps self-explanatory) may also request to join the X-PSI team without developing features.
Past developers are recognised as team members unless they no longer wish to be. Aside from acknowledging your contribution, this is useful for feature maintenance and as a contact point for questions, if permission is granted. Past team members will be acknowledged as such.
If you are a grant-holder and wish to base a major research project on the development and/or application of X-PSI, we invite you to discuss you (and your group where applicable) joining the X-PSI team in order to collaborate. If you find this idea interesting then please contact Anna L. Watts (contact details are on the Acknowledgements page). You are entirely free to develop X-PSI only in the public domain on GitHub, of course, but we can likely better organise and execute this work by using a mixture of private and public platforms. If you are applying X-PSI in research as an end-user, a private plaform for communication is probably desirable, and we invite you to request access to our Slack workspace.
X-PSI is an open-source project and we aspire that all X-PSI versions required for reproducibility of publications have release tags on GitHub.
End-users and community contributors can interact with the project freely on GitHub. If you wish to contribute code, either in the form of a patch, a tweak, or a feature, but you are uncertain about the workflow, we now provide an advisory workflow.
- Clone the
xpsirepository to your local computer:
git clone https://github.com/ThomasEdwardRiley/xpsi.git <path/to/xpsi>
- You will be on the
masterbranch by default; this branch by default tracks the official (or central)
masteris merely to act as an image of
origin/master, meaning that official upstream commits can always be applied to
mastervia a fast-foward merge.
- Checkout a local branch for your work, which we’ll assume is some patch, but could be a feature or otherwise:
git checkout -b patch/fix_something
- Commit your work to
git commit -m 'patch something'
- Check to see if any there are any new upstream commits, which would mean
git fetch origin master:master
- If the branches have diverged, you can either rebase
patch/fix_something, in either case resolving any conflicts:
git rebase master <or> git merge master
- Note that if you have already pushed
patch/fix_somethingto a remote repository you own (such as a fork of
xpsi; see below), and especially if this is accessible by others (e.g., via submitted pull request), you should only consider merging
patch/fix_somethingin order to preserve the branch history.
- After integrating upstream changes, you might decide to continue working on your branch. Alternatively, you could work on another branch for a different patch or feature. In either case you should repeat the process of integrating upstream changes as appropriate, and as a requirement if preparing for a pull request (although there could be exceptional corner cases wherein an X-PSI team member assists with this merging process).
- Once you are ready to contribute your work to the
xpsirepository, generally meaning that you have integrated any upsteam changes from
xpsi, you need a fork of the
xpsirepository on the same hosting platform (GitHub). You can create a fork using the GitHub GUI.
- With the address of your
forkyou can add it as a remote to your local repository:
git remote add fork https://github.com/<username>/xpsi.git
- Now push
fork, creating a remote branch
git push -u fork
- Now you can submit a pull request, using the GitHub GUI, from
xpsi/master. Please reference any open issues that are to be closed or are relevant to the proposed changes.
- You can update the pull-request topic branch by pushing additional commits
fork/patch/fix_something, which will update the pull request automatically:
- The pull request will then be reviewed and discussed. The proposed changes will either be merged or a merge will be pending because we request additional commits on the pull-request topic branch. Your pull request may be declined in some instances because the work reproduces development work that has already been performed but not published; your pull request may also be ultimately declined if it contains changes or implementations that we do not support or cannot maintain, and which cannot for some reason be separated from changes we do support and could maintain. Your intellectual contribution to the project will be gratefully acknowledged in the Acknowledgements and/or in the project History if this interaction leads to some form of merged development/implementation by another community member, even if your pull request is ultimately declined.
- If you co-authored a pull request with one or more collaborators, you can acknowledge them using the GitHub pull-request GUI as you would for a single commit. When a pull request is accepted, it is typically going to be via a merge-squash unless the history is clean or work will continue to be commited on the topic branch after the merge (where applicable). In this case it is the responsiblity of the X-PSI team member executing the merge to replicate the list of co-authors from the original pull request in the squash message.
- When a pull request is merged, conflicts will either need to be resolved locally by you as suggested above, ending in a pull request update, or by an X-PSI team member locally and then merged with or without a pull request.
- If you are ready to start development on a distinct patch or feature that is
not conditional on your open pull requests being merged, then you can apply
the workflow above by branching (again) off of an up-to-date
master. If your work is conditional on your open pull requests, you are free to continue your development by commiting to the relevant topic branch (or according to some other branching scheme). However, there is a risk that more work will be needed if the open pull request is not merged into the central repository; or if only a subset of proposed changes are merged; or conflict resolution does not favour all of the changes you proposed. Of course, such work may nevertheless remain useful in your own applications even if it is never all merged into the central repository. If the pull request is merged after your continuation, and the plan is submit a future pull request, you will have to merge in the
xpsi/masterbranch before opening another pull request so that the merge conflicts that were already resolved are not raised again.
- The above workflow also applies to remote branches other than
masterthat might exist in the
xpsirepository that you wish to contribute to, but this should be a less common pattern.
If you want to contribute a feature, you are welcome to communicate with us either on GitHub via issues and pull-requests, or on a private platform (see below).
Most feature development by the X-PSI team is conducted on private platforms including a private development repository .
The X-PSI team works with respect to a private centralised repository
xpsi_dev and pushes releases to a public GitHub repository. These veryy
online documentation pages are only built and pushed to GitHub to be hosted,
usually by a designated X-PSI team member responsible for this process.
Commits directly on GitHub via pull requests (e.g., patches) are fetched and
merged with the on-going development work.
Otherwise, the workflow with respect to the BitBucket repository is very similar
to the GitHub workflow. Development work is commited to branches which
are then merged into the
xpsi_dev/dev branch directly (for those with
write permissions) or by pull request. In this context
the role of the
xpsi/master branch on GitHub described above.
xpsi_dev branch is considered feature-complete for a release, it
will be merged into
xpsi_dev/master directly, or via a release branch.
xpsi_dev/master will be published to
xpsi/master via a fast-foward
merge. Alternatively, a local merge of
xpsi_dev/master might be needed, which is subsequently pushed to both
xpsi_dev. The definitive release commit will be tagged and the
tags pushed to both repositories.
X-PSI community members with access to
xpsi_dev, be it either with write
or read permissions (to some subset of branches), will add
xpsi_dev as a
remote to their local repository. Checking one’s remotes should yield output
(xpsi) [15:24:19][xpsi]$ git remote -v DEV https://ThomasEdwardRiley@bitbucket.org/ThomasEdwardRiley/xpsi_dev.git (fetch) DEV https://ThomasEdwardRiley@bitbucket.org/ThomasEdwardRiley/xpsi_dev.git (push) origin https://github.com/ThomasEdwardRiley/xpsi.git (fetch) origin https://github.com/ThomasEdwardRiley/xpsi.git (push)
If you have forked repositories (your own forks or those of other community
members for collaborative purposes) these would also be remotes of the local
repository and would be listed here. A local
master branch would track
xpsi/master. A local
dev branch would
xpsi_dev/dev. All other branches checked out from some upstream
source, be it an
xpsi branch, or a branch from another
community member’s fork, will track those remote branches. Branches that you
create and commit to locally will be pushed usually to your own fork for a pull
request, unless you have write permissions to push directly to another
A useful online description of a model on which this development structure is based is available.