OpenSCAD User Manual/Submitting patches

Patches can be submitted viahttps://github.com/AriesTriputranto Docs.github.com/AriesTriputranto]

The openscad project page is at https://github.com/openscad/openscad

Brief overview

OpenSCAD has no formal guidelines about tabs, spaces, etc. Try to match what exists already in the file you are working on.

QT should be avoided in everything except GUI code. Use C++11 or boost instead. The goal is to stay modular.

Modularity also extends to OpenCSG and CGAL. Note the #ifdefs that attempt to separate CGAL/OpenCSG dependent code from 'independent' code.

There are two build systems, Qmake for the GUI and Cmake for the test suites. Please test your patch under both. Read doc/testing.txt and README.md.

When including a new external library, please try to test it on many different systems. The GNU Compile Farm can help, as can emulator systems like Qemu or VMWare. Review the 'build-dependencies' scripts for Mac OSX and Linux/Unix (under /scripts). Try to do a cross-build to Windows if possible (see README.md)

Steps to follow to submit a patch

• Search the OpenSCAD mailing list on the topic to see if it has been previously discussed (ie. if want to add a patch for color, do a web search for 'openscad mailing list color'). Take those discussions into account when creating a patch.

• If you are not familiar with git, read a git tutorial thoroughly (like the one at [1])

• Sign up for a github account and read the introductory documentation thoroughly, for example http://help.github.com/fork-a-repo/

• Make your own fork of openscad on github

• Clone your new fork onto your local machine

• Hack away at openscad. Test your hack.

• Frequently merge the official openscad source back into your local copy, to avoid conflicts
  • http://help.github.com/fork-a-repo/ has instructions.

• Commit your changes to your local repository and push them back to your forked openscad on github

• Run all the regression tests by reading "doc/testing.txt". Make sure your patch won't break anything. Ask the mailing list if confused.

• If your patch adds a new feature, create a new regression test for it, and commit the test, and test result .png files, to your branch. See doc/testing.txt.

• Update any documentation, including the RELEASE NOTES, README.md, and openscad manpage to reflect your changes, if needed. Also be prepared to update the Wiki manual.

• When you are ready, click on the 'Pull Request' button on your fork at github. Carefully review the differences between your code and OpenSCAD Master branch.

• When you are ready, submit the pull request.

Alternative

Small patches can also be created using 'git diff' and posting to the mailing list at mailing list but github is vastly preferable.