- Contributing guidelines
Thank you for considering making a contribution to DynAdjust.
DynAdjust forms an integral component of public geospatial infrastructure and commercial software. It is used for the establishment and routine maintenance of Australia's Geospatial Reference System, the maintenance of International Terrestrial Reference Frame local ties, the computation of digital cadastre (or land parcel) fabrics, and a diverse array of engineering and geospatial projects. For these reasons, great emphasis is placed upon ensuring the DynAdjust code base is maintained using high quality coding standards.
The purpose of this page is to provide some contributing guidelines to help maintain a high quality code base, and to foster a positive and prosperous collaborative development culture.
To make any changes to the DynAdjust code base, suggest new features, or improve the documentation using GitHub, you will need a GitHub account.
Please familiarise yourself with GitHub's pull request process. Another useful resource is Aaron Meurer's tutorial on the git workflow.
If you plan to make changes to the code base, please ensure you have read the installation instructions and have obtained all the essential prerequisites.
The general process for addressing issues in DynAdjust is as follows.
- Search the list of open issues in the issue tracker for any occurrence(s) of the issue you would like to address.
- If it is closely related to an existing open issue, please add a comment to the open issue rather than to create a new issue.
- By default, the issue tracker displays open issues. Perhaps your issue relates to a defect previously marked as fixed, but remains unresolved. In this case, remove the
is:openswitch to search through all issues. If you feel the issue persists, reopen the issue and provide comments (as described in the next step). - If the issue has not been raised before, continue to the next step.
- Create a new issue, or reopen a closed issue.
- Defects. If it is a defect, please describe how to reproduce it and, if possible, provide sample command line arguments and snippets of the output which demonstrate the defect. Please select an appropriate label that characterises the issue.
- Enhancements. If it is an enhancement, please provide the desired or expected behaviour not presently delivered by DynAdjust. Please cite any relevant technical documents (e.g. journal articles, reference texts or other publications) that may help the developers address the issue. Wherever possible, provide some test cases demonstrating expected behaviour.
- Compilation. If your issue relates to compiler errors or warnings, please provide full details of the operating system and compiler version, and provide a snippet of the compiler error or warning produced.
- Feedback. Perhaps you'd like to share your thoughts on how DynAdjust can be improved. In this context, you can:
- Contribute code you already have. If it is not ready for production, we'd be glad to hear from you and to help you get it ready for the next release.
- Propose a new function or suggest an alternative formula/algorithm.
- Contribute suggestions, corrections or updates to the documentation.
- Share some sample data.
- Create your own separate fork of DynAdjust, or rebase your forked copy of DynAdjust to the latest version.
- Prepare for a specific pull request and begin making your changes.
- Ensure your changes relate to the discrete issue you're attempting to address. That is, don't try to solve or fix everything in the one change request.
- For new DynAdjust features, create a new test script that tests your work and provides satisfactory code coverage.
- Make sure all tests pass using the supplied
make_dynadjust_gcc.shscript. For instance, to build and test your changes, run the script as:$ make_dynadjust_gcc.sh -c -a -n -tThis will build the code base without cloning a fresh copy, no user interaction, no installation and will execute all cmake tests. For more information, please refer to the installation instructions. - Issue commits in logical packets of work, providing a clear message that describes what you're doing.
- When all commits for your change request are complete, issue a pull request. Please provide concise, clear and simple descriptions of your changes (and don't forget to check your spelling!). If required, please assign a reviewer you feel would be best placed to review your changes.
- People with sufficient permissions will review your changes and approve the request when they are satisfied. They may respond to you with questions or requests for further improvements.
Most discussions happen in the issue tracker or within pull requests. For general questions, please feel free to post to the repository's discussion page.
We encourage the use of language that is objective, professional, respectful and considerate of the wide user/developer audience. DynAdjust's audience has a diverse background, including theoretical geodesists, GIS users, software developers and senior level experts. Not everyone will understand the level of detail being discussed, however, it should be simple enough for those with the relevant domain knowledge to understand and respond to. In all cases, we encourgage you to model positive communication behaviours.
Primarily, all issues, defects, enhancements and queries should be tracked publicly using the repository's issue tracker. However, if you would like to submit a request or report privately (i.e. for cases when information should not be released publically), please direct your request ot report to geodesy@ga.gov.au.
DynAdjust implements a wide range of specialist geodetic and surveying algorithms and formulae. These have been sourced from journal articles, reference texts, published standards and other peer-reviewed publications. All functionality, algorithms and formulae have been documented in the DynAdjust User's Guide and are appropriately cited with the full biblographic reference. When proposing a new feature that implements an undocumented algorithm or formula, please cite its full reference with your comments.
Periodically, a DynAdjust Steering Committee meets to review the functionality of DynAdjust and to discuss potential enhancements. If you would like the Steering Committee to consider your thoughts on the future of DynAdjust, please submit your comments to geodesy@ga.gov.au.
DynAdjust development has evolved over 14 years from C++98 to C++14, with heavy reliance upon the Standard Template Library (STL). Wherever possible, Boost has been used to incorporate portable libraries unavailable within the C++ Standard. Over time, some of Boost's libraries features have become a part of the C++ Standard.
Current development is focussed on C++14. Various (older) parts of the code base is in C. Over time, these portions are being converted to C++. While there are many desirable features of C++20, such features aren't being pursued at the present time so as to provide greater compatibility with older compilers.
DynAdjust has been in development since late 2008. Consequently, the style of the code has evolved with the capability and experience of the developers. For this reason, different projects will exhibit different styles; so too will different functions within the same project. Where possible, please endeavour to conform with the style of the surrounding code.
Please consider writing code that can be implemented on the widest number of platforms and systems (e.g. UNIX, Linux, Windows, Apple), rather than contributing code or using a library of functions that is specific to one particular system. Boost has a range of functions that can be implemented on various systems. In certain cases, it will be inevitable to provide code to work around the system-specific commands and behaviours using #if defined (or other means).
The folder and file structure of the code base and supporting files is as follows:
- Code that is specific to a particular DynAdjust program is located in the
dynadjust/dynadjust/folder. The projects nameddna...wrapperare programs with user interfaces that can be executed from the command line. The projects without the...wrappersuffix are libraries that provide the specific functionality relating to that project. - Code that is general and consumed by all projects is located in the
dynadjust/include/folder. - User documentation and build scripts are located in the
resources/folder. - Sample data that you can use to test DynAdjust functionality is located in the
sampleData/folder.
The use of consistent, high quality coding standards is key to delivering high quality software and minimising defects. We encourage you to adopt and adhere to coding standards that are well respected or acknowledged by industry experts.
For the most part, coding standards and principles for best practice adopted for DynAdjust have been inspired from many sources, some of which include (in alphabetical order):
- Josuttis, N. M. (1999). The C++ Standard Library - A Tutorial and Reference. 1st edition. Addison-Wesley.
- Lakos, J. (1996). Large-Scale C++ Software Design. Pearson Education Limited.
- Meyers, S. (2001). Effective STL: 50 specific ways to improve your use of the standard template library. Addison-Wesley Longman Ltd.
- Meyers, S. (2005). Effective C++: 55 Specific Ways to Improve Your Programs and Designs. 3rd edition. Addison-Wesley Professional.
- Meyers, S. (2014). Effective Modern C++: 42 Specific Ways to Improve Your Use of C++11 and C++14. O'Reilly Media, Inc.
- Schäling, B. (2014). The Boost C ++ libraries. XML Press. Available online: https://boost.org.
- Stroustrup, B. (2013). C++ Programming Language. 4th edition. Addison Wesley.
- Williams, A. (2012). C++ Concurrency in Action: Practical Multithreading. 1st edition. Manning Publications.
Although code changes can occur frequently, we endeavour to deliver new releases on a regular basis to help developers of other software packages and products that depend upon DynAdjust to plan accordingly. The currently adopted release schedule cadence is six months.
The file make_dynadjust_gcc.sh provides a way to build the code and run tests on local copies and on GitHub via continuous integration (CI) script.
With every commit and pull request, the project is tested with a unit test suite managed by cmake (via CMakeLists.txt).
The DynAdjust repository uses an automated test suite managed by GitHub Actions and Travis to ensure new or changed code is built and tested in an automated way. In this context, continuous integration (CI) has been set up to invoke builds for Linux using the script test_coverage.yml.
To ensure the test suite adequately covers the code base (as much as practically possible), code coverage analysis is run on every commit and pull request. The code coverage analysis tool used for DynAdjust is coveralls.io. The developers are currently working on increasing the coverage provided by the cmake test suite (via CMakeLists.txt).
With every commit and pull request, Codecov and Codacy are run to perform static code analysis. The code base is undergoing regular review to address the remaining issues (some of which are insignificant).