CONTRIBUTING.md

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:
  • /var/log/vmtools/ansible_runs.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 main unless they're fixing a particular issue in a release. Once issues are in main, 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 automated testing via GitHub Actions, as well as 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

A series of automated tests, through GitHub Actions, are performed on each pull request submitted. These automated tests are primarily focused on style and best-practices and cannot yet test for the complete correctness of each change. Performing a few tests yourself prior to opening a pull request can make the process of reviewing your changes easier.

If the automated tests fail for your change and you aren't able to determine a specific cause or if you believe the failures are unrelated to the changes you made, leave a comment on the pull request and a reviewer will assist in troubleshooting.

There are two different methods of testing that can be perfomed. For nearly all changes, doing a test run of the Ansible playbooks in a test VM is a great way to quickly identify issues. For changes to the common and oem roles or the packer/ directory, a full Packer build can be performed.

Test Ansible Run

Testing changes to the Ansible playbook should be done in a separate VM from the one you use for your usual work, just in case something goes wrong. In order to test your changes, push your changes to GitHub, boot your VM, open the JMU CS VM Configuration program, and do the following:

1. Go to File > Settings...
2. Change the branch to main
3. Set the URL to https://github.com/jmunixusers/cs-vm-build
4. Re-run the base configuration and all roles that your change affects
5. Change the branch to the name of the branch you made your change on
6. Change the URL to the URL of your fork (https://github.com/USERNAME/cs-vm-build)
   • Replace USERNAME with your username on GitHub
7. Re-run the base configuration and all yours that your change affects

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 jGRASP and Eclipse. If your change affects gcc or similar utilities, please try to compile a basic C "Hello world" program.

Test Packer Build

If you would like to test a full build of the VM, our Packer configuration requires more features than what is available in the repositories of most Linux distributions. You can install the latest development version of Packer from the nightly downloads page. There are downloads available for:

• Windows
• Linux
• macOS

Once downloaded, unzip the file and execute packer. From there, you can follow the instructions in the REAMDE.

Backporting fixes

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

• Locally checkout a new branch based on the intended release
• 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 main.

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.