Skip to main content

Contributing code

As an open source project, XCG welcomes and values contributions from the community. This page documents the processes and guidelines around contributing in order to:

  1. Facilitate smooth collaboration between the project maintainers and contributors
  2. Encourage high-quality contributions that improve XCG for the rest of the community

As detailed in each package's "Installation" section, the source code for XCG packages can be found at https://github.com/GovTech-CSG/<pypi-package-name> (e.g. https://github.com/GovTech-CSG/govtech-csg-xcg-dangerousfunctions).

High-level contribution process​

XCG adopts the "fork and pull request" model commonly used by open source projects. The high-level steps of this model are given below:

  1. Create a GitHub issue detailing what the proposed change is and why you are proposing it. Use one of the pre-defined issue templates if appropriate.
  2. Discuss the proposal with the maintainers via the issue thread in order to agree on a high-level implementation
  3. Use the fork and pull request workflow to submit your code changes:
    1. Fork this project to your own GitHub account and clone it to your local development environment
    2. Before making any changes, run the existing tests to confirm that they pass on your system. If they fail and you are unable to diagnose the failure yourself, create another issue to report the failure. Make sure to search the existing issues, both open and closed, to make sure you are not submitting a duplicate report.
    3. Once you've made sure existing tests are passing, start by writing new tests that assert the expected behaviour from your change, making sure that they fail
    4. Make your changes and run the entire test suite again, making sure all the tests (both old and new) now pass
    5. Send a GitHub pull request targeting this repository's main branch
    6. Make refinements to your change based on comments from the code reviewer(s)
  4. Finally, one of the maintainers will merge your changes into main

Code quality guidelines​

To simplify the enforcement of basic code quality requirements, XCG provides tooling that help developers automate the process. More specifically, we use the pre-commit tool to perform linting and formatting before each commit, thus ensuring consistency of formatting and style. Potential contributors should follow the instructions in each GitHub project's README to install and configure pre-commit in order to meet the minimum contribution standard.

That said, there is a lot more in the idea of "code quality" than just formatting and style. For matters going beyond these basics, a good reference to use would be Google's Python style guide, which lays out helpful guidelines for issues like when/how to use exceptions, or when to use syntactic sugar features such as Python decorators. Note: Do leave formatting and linting to the provided pre-commit hooks and refer to the Google guide only for higher-order issues.