This repository has been created to document and execute the configuration of e-Science services at sites in the Africa-Arabian region. That's a big place ! We want to be able to collate the experience and expertise of site administrators into a repository of knowledge that will enable sustainable development of distributed computing in Africa and Arabia. However, we also want to make sure that if people want to contribute, they can.
We chose github because the workflow of contibuting to repositories maintained within it is pretty standard; we don't want to re-invent the wheel of collaboraiton. So, if you have an idea, some code lying around, or you've noticed some error in the way we've done things, please send us a pull request. Don't be shy, we're nice people :)
If you use this code (and we want you to 😄), we consider it a moral responsibility to help improve it. The easiest way to do this is to report issues. While we can't guarantee support, we will do our best to respond to and close tickets that are assigned to the repo.
We have a public board where you can see our plans and status of issues in a pipeline : https://waffle.io/AAROC/devops
You can do your bit by trying to stick to a few guidelines :
- Are you having an Ansible problem ? Please google the issue at least once and check if it has been reported before somewhere. It at all possible, provide a reference to this in your ticket. This will save us a lot of time to diagnose the issue.
- Are you reporting an issue, or commenting on the code ? Issues go here. Commenting and discussing the code can be done with us at slack (ask for an invite if you're not on the team) or at the discussion forum (use the Sci-GaIA discussion forum for now, then we'll move on).
- Please report one and only one problem per issue. This may seem like a lot of overhead initially, but it helps us in the future to find solutions that actually work.
- If you have an actual error from an Ansible playbook, send us the full output of the relevant role. 1. Do not just send the last task, with the error - we will need some context 2. Be sure to mention relevant variables that you may have used
- It always helps to have your inventory and group_vars along with the issue.
- Be sure that you're using the right version of Ansible (currently v.9 or higher)
Understanding submitted issues is not just a matter of reading some console output or log file - some context is needed. Also, plain text is not a great way to communicate emphasis or context. Github issues provides a good syntax for reporting the issues, with highlighting for many different languages.
Please use Github flavoured markdown to submit issues. In particular, use the syntax highlighter to highlight code, or output on the terminal, logs, etc.
I.E :
[shell](user)~ echo hi
hiIt's very important for us to know when to close issues, as well as how issues were closed.
- If you find a fix, please report it and close the issue
- Try to flag the issue as SOLVED (either by writing it in the text, or setting the issue flag)
We usually request that commits are tested before inclusion, but this can requirea fairly complicated staging environment or continuous integration service which you may not have access to. You are welcome to use the .travis.yml example in the top directory if you're developing services which can be tested on travis-CI's platform. For more sophisticated testing, you may need access to a dedicated environment. Contact us to see whether we can make a cloud testbed avaiable for your use case.
It is good practice to run a simple sanity tests on Ansible playbooks before committing:
- Use
--syntax-checkto check the syntax of the playbook without executing it - Also, using the "dry-run"
--checkto predict changes that may take place
First of all, fork the repo to your own account and give it a meaningful name like "New role XXX" or "Puppet Manifest for Awesome Service Y". This will make it clear to us why you are eventually requesting the pull into the main repo.
This repository contains Puppet and Ansible code for instantiating production services. The master branch is where all the development happens. If you have a contribution which fixes or improves code in the master branch, by all means, send a pull request.
If you want to try out something new and need this repo for code base, please create a new branch called dev and make changes to that. Pull requests should be made on the dev branch on this repo. Merges from dev to master will happen after Operations meetings.
Please feel free to use the github issues to submit support requests or discuss issues. Please make sure that you mark issues accurately with the provided tags (e.g. questions should be specifically marked as such, etc.). We use the Waffle board for project planning.
We treat this repository as a piece of research infrastructure. It is the expression, in code, of services which enable science, and is part of a platform. We believe that platform needs to be properly communicated, citable, re-usable and that contributions should be attributable to the correct people. This is an aspirational statement, since doing this properly can be quite difficult.
This is also a very fast-moving field... we do what we can to keep up, and keep with the principles above.
The typical workflow is :
- If a new service or feature is contributed, this should be included as a submodule in the relevant directory
- An example of how this functionality is expressed in the real world should be then sent as a pull request.
- A period of peer review is under taken once automated tests are completed.
- The contributor is added to the
.zenodo.jsondescription of the repository. - A release is written describing the new functionality - this should be the equivalent of a mini-article.
This is experimental. We created a Journal to add these publications. The journal is edited by @brucellino and reviewed by ... a bunch of people...