Skip to content

Latest commit

 

History

History
121 lines (79 loc) · 7.64 KB

CONTRIBUTING.md

File metadata and controls

121 lines (79 loc) · 7.64 KB
Raw

BoxLang Contributing Guide

Hola amigo! I'm really excited that you are interested in contributing to BoxLang. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

Code Of Conduct

This project is open source, and as such, the maintainers give their free time to build and maintain the source code held within. They make the code freely available in the hope that it will be of use to other developers and/or businesses. Please be considerate towards maintainers when raising issues or presenting pull requests. We all follow the Golden Rule: Do to others as you want them to do to you.

  • As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
  • Participants will be tolerant of opposing views.
  • Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
  • Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
  • When interpreting the words and actions of others, participants should always assume good intentions. Emotions cannot be derived from textual representations.
  • Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

Bug Reporting

BoxLang tracks its issues in Jira and each module track it's own issues in its repo.

If you file a bug report, your issue should contain a title, a clear description of the issue, a way to replicate the issue, and any support files that we might need to replicate your issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix for it. All issues that do not contain a way to replicate will not be addressed.

Support Questions

If you have any questions on usage, professional support or just ideas to bounce off the maintainers, please do not create an issue. Leverage our support channels first.

Pull Request Guidelines

  • The master branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against the master branch. They will be closed.
  • All pull requests should be sent against the development branch.
  • It's OK to have multiple small commits as you work on the PR - GitHub will automatically squash it before merging.
  • Make sure all local tests pass before submitting the merge.
  • Please make sure all your pull requests have companion tests.
  • Please link the Jira issue in your PR title when sending the final PR

Security Vulnerabilities

If you discover a security vulnerability, please send an email to the development team at security@ortussolutions.com and make sure you report it to the #security channel in our Box Team Slack Channel. All security vulnerabilities will be promptly addressed.

Development Setup

We have added all the necessary information for you to develop on BoxLang in our readme collaboration area.

Language Compatiblity

Please make sure you use JDK21+.

Coding Styles & Formatting

We are big on coding styles and have included two codings styles for you to follow:

# Format everything
box run-script format

# Start a watcher, type away, save and auto-format for you
box run-script format:watch

We recommend that anytime you hack on the core you start the formatter watcher (box run-script format:watch). This will monitor your changes and auto-format your code for you.

You can also see the Ortus Coding Standards you must follow here: https://github.com/Ortus-Solutions/coding-standards

Financial Contributions

You can support ColdBox and all of our Open Source initiatives at Ortus Solutions by becoming a patreon. You can also get lots of goodies and services depending on the level of contributions.

Technical Documentation

The technical documentation for the Types, Built In Functions, Components and Exceptions sections of the official documentation are generated directly from the BoxLang source code Javadoc comment blocks. In order to ensure this documentation is accurate, please ensure any submissions in the areas of BIFs, Member Functions, Components, BoxLang types, and Exceptions are well documented.

For BIFs and member functions, granular argument documentation is required. For Java classes containing multiple BIFs or member functions, you may use custom annotations to separately describe each BIF. See the TimeUnits.java _invoke method for an example of how this is accomplished. You may also exclude attributes and arguments from being documented for a particular functions. The syntax for this is:

@function.MyFunction.arguments.exclude myArgument

To preview this documentation run the following command:

gradle generateTechnicalDocumentation

This will place all of the generated documentation in the docs directory. The Summary.md file generated in the root of that directory, represent the navigation items to be spliced in to the SUMMARY.md file for the above linked sections. Documentation changes are synchronized on each release with the following process:

  1. Run gradle generateTechnicalDocumentation on the source code.
  2. Clone the documentation repository as a sibling of the source code repository
  3. Syncronize the changes between the two repositories using rsync : rsync -Irav --update $PWD/docs/boxlang-language/reference/ $PWD/../boxlang-docs/boxlang-language/reference
  4. Splice in the full contents of the generated docs/Summary.md, replacing the existing sections

Contributors

Thank you to all the people who have already contributed to BoxLang! We: heart: : heart: : heart: love you!

Made with contributors-img