v2.2 LTS
Masonite Essentials
Contributing Guide

When contributing to this repository, please first discuss the change you wish to make via an issue or in the Masonite Slack channel.
Please note we have a code of conduct, please follow it in all your interactions with the project. You can find it in the base of the core project directory.

The framework has three main parts.
This MasoniteFramework/masonite repository is the main repository that will install when creating new projects using the craft new command. This is actually a full Masonite project. Not much development will be done in this repository and won't be changed unless new releases of Masonite require changes in the default installation project.
The MasoniteFramework/core repository is where the main masonite pip package lives. This is where the from masonite ... module lives.
The MasoniteFramework/craft repository where the craft command lives. This is the actual command itself and is installed when you run pip install masonite-cli --user.

This repo is simple and will be able to be installed following the installation instruction in the README.
  • Fork the MasoniteFramework/masonite repo.
  • Clone that repo into your computer:
    • git clone http://github.com/your-username/masonite.git
  • Checkout the current release branch (example: develop)
    • git checkout -b develop
  • You should now be on a develop local branch.
  • Run git pull origin develop to get the current release version.
  • From there simply create your feature branches (<feature|fix>-<issue-number>) and make your desired changes.
  • Push to your origin repository:
    • git push origin change-default-orm
  • Open a pull request and follow the PR process below

The trick to this is that we need it to be pip installed and then quickly editable until we like it, and then pushed back to the repo for a PR. Do this only if you want to make changes to the core Masonite package
To do this just:
  • Fork the MasoniteFramework/core repo,
  • Clone that repo into your computer:
    • git clone http://github.com/your-username/core.git
  • Activate your masonite virtual environment (optional)
    • Go to where you installed masonite and activate the environment
  • While inside the virtual environment, cd into the directory you installed core.
  • Run pip install . from inside the masonite-core directory. This will install masonite as a pip package.
  • Any changes you make to this package just push it to your feature branch on your fork and follow the PR process below.
This repository has a barebones skeleton of a sample project in order to aid in testing all the features of Masonite against a real project. If you install this as editable by passing the --editable flag then this may break your project because it will override the modules in this package with your application modules.

Craft commands make up a large part of the workflow for Masonite. Follow these instructions to get the masonite-cli package on your computer and editable.
  • Fork the MasoniteFramework/craft repo,
  • Clone that repo into your computer:
    • git clone http://github.com/your-username/craft.git
  • Activate your masonite virtual environment (optional)
    • Go to where you installed masonite and activate the environment
  • While inside the virtual environment, cd into the directory you installed cli
  • Run pip install --editable . from inside the masonite-cli directory. This will install craft (which contains the craft commands) as a pip package but also keep a reference to the folder so you can make changes freely to craft commands while not having to worry about continuously reinstalling it.
  • Any changes you make to this package just push it to your feature branch on your fork and follow the PR process below.

Comments are a vital part of any repository and should be used where needed. It is important not to overcomment something. If you find you need to constantly add comments, you're code may be too complex. Code should be self documenting (with clearly defined variable and method names)

There are 3 main type of comments you should use when developing for Masonite:

All modules should have a docstring at the top of every module file and should look something like:
"""This is a module to add support for Billing users."""
from masonite.request import Request
...
Notice there are no spaces before and after the sentence.

All methods and functions should also contain a docstring with a brief description of what the module does
For example:
def some_function(self):
"""This is a function that does x action.
Then give an exmaple of when to use it
"""
... code ...

Most methods will require some dependency or parameters. You must specify them like this:
def route(self, route, output):
"""Load the route into the class. This also looks for the controller and attaches it to the route.
Arguments:
route {string} -- This is a URI to attach to the route (/dashboard/user).
output {string|object} -- Controller to attach to the route.
Returns:
self
"""
And if your dependency are object it should give the path to the module:
def __init__(self, request: Request, csrf: Csrf, view: View):
"""Initialize the CSRF Middleware
Arguments:
request {masonite.request.Request} -- The normal Masonite request class.
csrf {masonite.auth.Csrf} -- CSRF auth class.
view {masonite.view.View} -- The normal Masonite view class.
"""
pass

If you're code MUST be complex enough that future developers will not understand it, add a # comment above it
For normal code this will look something like:
# This code performs a complex task that may not be understood later on
# You can add a second line like this
complex_code = 'value'
perform_some_complex_task()

  1. 1.
    You should open an issue before making any pull requests. Not all features will be added to the framework and some may be better off as a third party package or not be done at all. It wouldn't be good if you worked on a feature for several days and the pull request gets rejected for reasons that could have been discussed in an issue for several minutes.
  2. 2.
    Ensure any changes are well commented and any configuration files that are added have a docstring comments on the variables it's setting.
  3. 3.
    Update the README.md and MasoniteFramework/docs repo with details of changes to the interface, this includes new environment variables, new file locations, container parameters etc.
  4. 4.
    Name your branches in the form of feature|fix-<issue-number>. For example if you are doing a bug fix and the issue number is 576 then name your branch fix-576. This will help us locate the branches on our systems at later dates. If it is a new feature name it feature-576.
  5. 5.
    You must add unit testing for any changes made. Of the three repositories listed above, only the craft and core repos require unit testing.
  6. 6.
    Increase the version numbers in any example files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is RomVer.
  7. 7.
    The PR must pass the Travis CI build. The Pull Request can be merged in once you have a successful review from two other collaborators, or one review from a maintainer or Masonite creator.

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Examples of behavior that contributes to creating a positive environment include:
  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints and experiences
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
  • The use of sexualized language or imagery and unwelcome sexual attention or advances
  • Trolling, insulting/derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or electronic
    address, without explicit permission
  • Other conduct which could reasonably be considered inappropriate in a
    professional setting

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
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 to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected] All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4
Export as PDF
Copy link
On this page
Contributing Guide
Introduction
Getting Started
Getting the Masonite repository up and running to be edited
Types of comments to use
Module Docstrings
Method and Function Docstrings
Methods and Functions with Dependencies
Code Comments
Pull Request Process
Code of Conduct