|
| 1 | +# Contributing Guide |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +When contributing to this repository, **please first discuss the change you wish to make via issue, email, or any other method with the owners or contributors of this repository** before making a change 😃 . Thank you ! |
| 6 | + |
| 7 | +## Getting Started |
| 8 | + |
| 9 | +### Get the code |
| 10 | + |
| 11 | +First you should configure your local environment to be able to make changes in this package. |
| 12 | + |
| 13 | +1. Fork the `https://github.com/py-package/masonite-sentry` repo. |
| 14 | +2. Clone that repo into your computer: `git clone http://github.com/your-username/sentry.git`. |
| 15 | +3. Checkout the current release branch \(example: `master`\). |
| 16 | +4. Run `git pull origin master` to get the current release version. |
| 17 | + |
| 18 | +### Install the environment |
| 19 | + |
| 20 | +1. You should create a Python virtual environment with `Python >= 3.7`. |
| 21 | +2. Then install the dependencies and setup the project, in root directory with: |
| 22 | + |
| 23 | +``` |
| 24 | +make init |
| 25 | +``` |
| 26 | + |
| 27 | +**Note:** |
| 28 | + |
| 29 | +- The package will be locally installed in your venv (with `pip install .`). Meaning that you will be |
| 30 | + able to import it from the project contained in the package as if you installed it from PyPi. |
| 31 | +- When making changes to your packages you will need to uninstall the package and reinstall it with |
| 32 | + `pip uninstall sentry && pip install .` |
| 33 | + |
| 34 | +### Contribute |
| 35 | + |
| 36 | +- From there simply create: |
| 37 | + - a feature branch `feat/my-new-feature` |
| 38 | + - a fix branch `fix/my-new-fix` |
| 39 | +- Push to your origin repository: |
| 40 | + - `git push origin feat/my-new-feature` |
| 41 | +- Open a pull request (PR) and follow the PR process below |
| 42 | + |
| 43 | +1. You should open an issue before making any pull requests. Not all features will be added to the package and some may be better off as another third party package. 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. |
| 44 | +2. Ensure any changes are well commented and any configuration files that are added have a flagpole comment on the variables it's setting. |
| 45 | +3. Update the README.md if installation/configuration or usage has changed. |
| 46 | +4. It's better to add unit tests for the changes you made. |
| 47 | +5. The PR must pass Github CI checks. The PR can be merged in once you have a successful review from a maintainer. |
| 48 | +6. The version will be bumped by the maintainer when merging, so don't edit package version in the PR. |
| 49 | + |
| 50 | +### Testing |
| 51 | + |
| 52 | +- To add unit tests add tests under `tests/` directory, please read about [Masonite |
| 53 | + testing](https://docs.masoniteproject.com/useful-features/testing) in the official |
| 54 | + documentation |
| 55 | + |
| 56 | +- To test your package locally in a project, a default Masonite project is available |
| 57 | + at root. Just run `python craft serve` and navigate to `localhost:8000/` and |
| 58 | + you will see `Hello Package World` in your browser. |
| 59 | + |
| 60 | +## Dev Guidelines |
| 61 | + |
| 62 | +### Package development |
| 63 | + |
| 64 | +You should read guidelines on package creation in the [Official Documentation](https://docs.masoniteproject.com/advanced/creating-packages) |
| 65 | + |
| 66 | +### Comments |
| 67 | + |
| 68 | +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\) |
| 69 | + |
| 70 | +#### Types of comments to use |
| 71 | + |
| 72 | +There are 3 main type of comments you should use when developing for Masonite: |
| 73 | + |
| 74 | +**Module Docstrings** |
| 75 | + |
| 76 | +All modules should have a docstring at the top of every module file and should look something like: |
| 77 | + |
| 78 | +```python |
| 79 | +""" This is a module to add support for Billing users """ |
| 80 | +from masonite.request import Request |
| 81 | +... |
| 82 | +``` |
| 83 | + |
| 84 | +**Method and Function Docstrings** |
| 85 | + |
| 86 | +All methods and functions should also contain a docstring with a brief description of what the module does |
| 87 | + |
| 88 | +For example: |
| 89 | + |
| 90 | +```python |
| 91 | +def some_function(self): |
| 92 | + """ |
| 93 | + This is a function that does x action. |
| 94 | + Then give an exmaple of when to use it |
| 95 | + """ |
| 96 | + ... code ... |
| 97 | +``` |
| 98 | + |
| 99 | +**Code Comments** |
| 100 | + |
| 101 | +If you're code MUST be complex enough that future developers will not understand it, add a `#` comment above it |
| 102 | + |
| 103 | +For normal code this will look something like: |
| 104 | + |
| 105 | +```python |
| 106 | +# This code performs a complex task that may not be understood later on |
| 107 | +# You can add a second line like this |
| 108 | +complex_code = 'value' |
| 109 | + |
| 110 | +perform_some_complex_task() |
| 111 | +``` |
| 112 | + |
| 113 | +**Flagpole Comments** |
| 114 | + |
| 115 | +Flag pole comments are a fantastic way to give developers an inside to what is really happening and for now should only be reserved for configuration files. A flag pole comment gets its name from how the comment looks |
| 116 | + |
| 117 | +```text |
| 118 | +""" |
| 119 | +|-------------------------------------------------------------------------- |
| 120 | +| A Heading of The Setting Being Set |
| 121 | +|-------------------------------------------------------------------------- |
| 122 | +| |
| 123 | +| A quick description |
| 124 | +| |
| 125 | +""" |
| 126 | +
|
| 127 | +SETTING = "some value" |
| 128 | +``` |
| 129 | + |
| 130 | +It's important to note that there should have exactly 75 `-` above and below the header and have a trailing `|` at the bottom of the comment. |
0 commit comments