Notice¶

Work-in-progress document discussing future MailCleaner development. The 'Legacy' model is still in use until this Notice is removed.

Legacy development process¶

MailCleaner development is done using Git and updates distributed via GitHub. Historically, this has been done by having developers fork, contribute to a branch on their fork, then use a Pull Request to merge into the 'master' branch. This methodology allows anyone to contribute and for changes to be tested by checking out those pull requests onto a testing machine before merging.

However, this methodology is inflexible at best and having no intermediate step between limited testing on those development machines and pushing out to the entire user-base has proven to be insufficient to catch all use-cases.

Current development process¶

We have begun utilizing a system of branches within MailCleaner's GitHub repository.

For contributors, Community Edition users and unregistered users, not much will change. Contributors (staff or community) will still contribute to a branch on their fork and open a pull request to merge to 'master'. 'master' now serves as the 'latest' branch.. These commits will be tested similar to how they always have been before merging. These users will function as a wider testing community for the Enterprise Edition. This is similar to how Fedora Linux users get the latest features and serve as the testing community for RedHat Enterprise Linux.

'stable' branch¶

Enterprise Edition users will fetch and checkout the 'stable' branch when they register. This branch will track behind by anywhere from one commit to a longer time-based delay depending on the likelihood for the changes in 'master' to cause issues. We will monitor for fallout before our senior development team rebases to include the changes in 'master'.

'stable' is not intended to be used in Enterprise Edition or on unregistered machines. There are to be some safeguards in place to ensure that this does not happen. While the 'stable' branch will still be open source and published on GitHub, be ask that our users abide by this policy. These users will be expected to run the latest version of MailCleaner to get all the newest features immediately. They will help to ensure even better support for our paid subscribers who help keep MailCleaner running. It is not in anyone's interest to requires us to spend time implementing any stronger safeguards than the modest ones currently in place in order to avoid having 'crackers' try to subvert our registration policy.

'feature' branches¶

It is possible that we may have a need to provide optional functionality on a more select basis. To allow for this, the 'Updater4MC' script has been updated to allow for a declaration of the branch you would like to start tracking. This can be done like

$ /root/Updater4MC/updater4mc.sh --mc-branch=feature --u4mc-branch=testing

This will checkout the branch 'feature' for '/usr/mailcleaner' and 'testing' for '/root/Updater4MC'. Those values will each respectively be stored in:

/var/mailcleaner/spool/updater/mc-branch
/var/mailcleaner/spool/updater/u4mc-branch

so that they will continue to be pulled from. You can omit either to continue using whichever branch is currently logged in the relevant file, or use 'master' or 'stable' for each to resume tracking the production branch.

Feature branches may be utilized to implement 'tags' to introduce an additional level of feature stability by locking that branch at a specific revision.

Note that we will not guarantee functionality for checking out feature branches which are further behind your machines latest update. Changes to the database can be introduced which would cause prior revisions not to work as expected. Those changes - applied via Updater4MC - cannot easily be rolled back.

The future¶

The MailCleaner team is working hard towards a new major version of the product. This major leap will see an entirely new paradigm in how updates are distributed. Specifically, core parts of MailCleaner are going to be provided as containers. In this paradigm, the container images will be similarly versioned with 'stable' and 'latest' where Enterprise Edition users will pull the former. Development will continue in GitHub for the foreseeable, but the method for deploying MailCleaner will change significantly. The implementation of the current development methodology is a step in that direction.

Contributing¶

If you'd like to contribute to MailCleaner, now, in the past, or in the future, you need to make a fork of our GitHub repository(ies):

https://github.com/MailCleaner/MailCleaner
https://github.com/MailCleaner/Updater4MC

Once forked, update the git config on your development machine so that 'origin' is your fork. You can rename our 'remote' to something like 'upstream' so that you can rebase later. eg:

$ cat .git/config
[core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
[remote "upstream"]
    url = https://github.com/MailCleaner/MailCleaner.git
    fetch = +refs/heads/*:refs/remotes/origin/*
[remote "origin"]
    url = git@github.com:JohnMertz/MailCleaner.git
    fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
    remote = origin
    merge = refs/heads/master

While it is not necessary, to develop on a branch of your fork, it is still generally recommended. You can checkout a development branch with:

$ git checkout -b branch_name

Your development branch should always be based on the upstream master. If your branch falls behind, ensure that it is successfully rebased before committing any changes:

git pull --rebase upstream master

Once you are ready to make a pull request, you can push to your fork. If you are on a branch which already exists on GitHub, use:

git push

Otherwise create the branch on GitHub with:

git push --set-upstream origin branch_name

You can then create a Pull Request within the GitHub UI. Please feel free to contact us via a GitHub Issue if you have any questions or concerns prior to opening a Pull Request.