Contributing to the cfengine design center

Please read this guide if you would like to contribute new sketches to the CFEngine Design Center. This guide explores the structure of the repository, and describes the steps you have to follow to submit a new sketch.

You probably want to read the Writing DC Sketches document for details about the structure of the sketches themselves.

How to contribute to the Design Center

The Design Center repository is hosted at GitHub, and we encourage you to use GitHub's Fork + Pull model to send contributions.

Here is how it works:

1. Create (if needed) and configure (Mac, Windows, Linux) your GitHub account.

2. Fork the cfengine/design-center repository.

   

3. Once the fork is complete, you will be automatically taken to your fork of the repository. You now need to check it out. You can copy the URL from your GitHub page (red arrow).

   

   The git command to check out your fork looks like this:

   git clone git@github.com:yourusername/design-center.git
   

4. Create a new git branch based off of master for each independent set of changes you want to submit. This will allow you to submit several pull requests at once without them interfering with each other. For example:

   git checkout master && git checkout -b webalizer_sketch
   

5. Make any changes or additions you want to contribute. Make sure you follow the Sketch Coding Guidelines described in Writing DC Sketches.

6. Make sure all your changes are both committed to your local git repository (git add and git commit) and pushed to your fork of the repository on github (git push). For example, if you have added a new sketch under sketches/web_apps/webalizer.cf, you could use the following commands:

   $ git add sketches/web_apps/webalizer.cf  # Stage the file
   $ git commit -m "Sketch for Webalizer"    # Commit to local repository
   $ git push origin webalizer_sketch        # Push to your fork repository in the webalizer_sketch branch
   

7. Once all your changes are pushed into your own fork of the repository, create a Pull Request for them to be merged into the main repository. You can follow the detailed instructions at GitHub if you are unfamiliar with the process.

   

8. After submission, you can view the pull request at https://github.com/cfengine/design-center/pulls. You may also comment (or view others' comments) on the pull request. The repository maintainers may have comments or requests for changes before the pull request is accepted.

9. Once the pull request is accepted, your changes will be incorporated into the main repository.

Community evaluation of contributed Sketches

The CFEngine users community is asked to comment on all submissions to the Design Center by simply subscribing to the pull request activity on Github. Each pull request will be accepted after review and testing; depending on the depth and breadth of the changes more than a few rounds may be needed. Ultimately, regardless of comments, a repository moderator (currently, a CFEngine AS engineer) will decide whether a submission is accepted.

All CFEngine community members are invited and encouraged to participate in this evaluation process by monitoring the Design Center pull requests.

The testing should include:

• Functionality: Does the sketch do what it says it does? Does it do it well?
• Safety: is the sketch malicious or incorrect in any way? A contribution need not be malicious to be unsafe. If it makes it extremely easy for a system to get corrupted or destroyed, then it should be modified with the appropriate safeguards and documentation.
• Documentation: is the usage of the sketch clear from the included documentation? It does not necessarily have to be easy to use, but its use should be well documented.
• Metadata: is all the required metadata (see below) included and correct?
• Orthogonality: is the functionality of the sketch partially or completely covered already by an existing sketch? If so, it should probably be resubmitted as an update to the existing sketch rather than a completely new one.

It is our intention that these rules as flexible and applied according to the best judgement of the community, to encourage agility while maintaining a certain level of quality.

Above all, we encourage you to participate and contribute! If you have any questions or suggestions, please feel free to post them in the CFEngine Help forum or send email to design-center@cfengine.com. We look forward to your feedback and contributions!