Skip to content

Files

Latest commit

 

History

History
161 lines (120 loc) · 6.86 KB

CONTRIBUTING.md

File metadata and controls

161 lines (120 loc) · 6.86 KB

Contributing to cs-vm-build

The JMU Unix Users Group welcomes contributions to its projects. This document is not intended to serve as a list of rules for contributing to JMU UUG projects, but rather its intent is to document the process and prepare potential contributors for what to expect.

This document assumes a basic knowledge of git and GitHub. For an intro to both of these, see our git intro guide.

Getting started

Before adding a new feature or a new course, please open an issue to start discussion before beginning work. This will prevent several people accidentally working on the same feature and will ensure that everyone has a similar goal for the new feature.

Please keep in mind that this project is specifically focused on providing a service to JMU's CS department and students. Some feature requests may not be approved if they stray too far away from that goal.

Reporting issues

It is significantly easier to troubleshoot issues when detailed bug reports are provided. Effective bug reports generally contain:

  • Complete logs or recent entries from logs generated by Ansible and the wrapper script. These files are located at:
    • /opt/vmtools/logs/last_run.log
    • ~/.cache/uug_ansible_wrapper.log
  • A description of troubleshooting steps taken
  • Exact error message text or screenshots

Clearly not all of these will apply to all issues; however, it's often easier for us to parse through extra information than to collect additional information.

Submitting pull requests

Pull requests should be targeted to master unless they're fixing a particular issue in a release. Once issues are in master, they may be backported. This allows us to ensure that the next release of the VM includes all fixes that are in the current release.

We strongly suggest doing your work in topic branches for the particular pull request; this will make testing significantly easier for you and for the UUG.

Pull request reviews

Your pull request will be reviewed by at least one member of the UUG Virtual Machine team. We require all pull requests (even ones from UUG Virtual Machine team members) to go through a review process before merging. Your reviewers may request that some changes be made before merging or may merge your pull request as-is.

Reviewers are encouraged to provide specific feedback and help contributors improve their patches.

Testing

Performing a few tests before submitting a pull request can significantly decrease the amount of time before your PR is merged and will make life much easier for your reviewers. We recommend the following for testing:

  • Have a dedicated VM for testing your fixes that you don't use for other work
  • In the JMU CS VM Configuration program:
    • Go to File > Settings...
    • Change the branch to master
    • Change the URL to https://github.com/jmunixusers/cs-vm-build
    • Re-run the base configuration and all roles that your change will affect
    • Change the branch and URL to where you pushed your changes
    • Re-run the base configuration and all roles that your change will affect

At this point, you can test and ensure that your change works as expected. If your change affects Java, please try to compile a basic Java "Hello world" program in each of: DrJava, jGRASP, and Eclipse. If your change affects gcc or similar utilities, please try to compile a basic C "Hello world" program.

Backporting fixes

When a fix needs to be backported from master to a particular release, the following has worked relatively well.

  • Locally checkout a new branch based on master
  • Run git pull https://github.com/jmunixusers/cs-vm-build master
  • Run git cherry-pick <COMMIT_HASH> for each commit that needs to be backported.
  • Run git push origin BRANCH
  • Create a pull request targeting the release the fix is for

Backports go through the same review process as any other commits. In the pull request, please reference the number of the pull request from when the fix was merged into master.

Preparing for a release

Release branches have the same name as the Linux Mint release that they correlate with. For example, sylvia or tara.

Tags have the following naming scheme: RELEASE-SSYYA where:

  • RELEASE is the Linux Mint codename for the release
  • SS is either fa for fall releases for sp for spring releases
  • YY is the last two digits of the calendar year of the release
  • A is an alphabetical release.

For example, the first release in the spring of 2018 was sylvia-sp18a and if subsequent releases had been necessary, they would have been named sylvia-sp18b and sylvia-sp18c, etc. The first release in fall 2018 was tara-fa18a.

Adding a new role

Assuming you have your git operations in order, the first thing you will need to do to begin working on your ansible role is to create the directory. We will start in the base cs-vm-build directory that you get when cloning the jmunixusers repo. First move into the roles/ folder, and create a directory for your role using the ansible-galaxy command:

ansible-galaxy init [your class name/description]

This has very little output but once it finishes, go into the newly created directory to find a host of new folders and a readme. Every folder (generally) contains a main.yml file that will be your base for your new role. Try to keep to the tasks/main.yml and vars/main.yml if you are unsure about where to put things, though there are good reasons to use other folders/files.

As you will see in many of the other roles, any lists are generally kept to the vars folder, since it places them in a place that is easy to access and decoupled from the actual implementation of what those variables are needed for.

One last note; we have tried to avoid using external ansible modules, as they are usually simply a shell command wrapped in a python script. For any install that can be done with a command module call instead of a more specific module generally should, as using a seperate module would require installing that module on every VM, as we are not using ansible as it was designed.

Afterwords, simply add your role to the roles.yml file in the root of the project. It should be fairly obvoius to see, but just in case here is the layout:

- { role: [role name], tags: ['tags'] )

Now we are ready to edit the python installer. Navagate to cs-vm-build/roles/common/files and open uug_ansible_wrapper.py. You will be greeted with a long and hard to read python file, but luckily the only thing we need to edit is very early in the file. On line 33 (at the time of writing) there is a dictionary of classes and tags, this is where we will be adding our class. The first value is what the class will appear as in the install program, and the second value will be the role name from the roles.yml file we added earlier.