Overview

🚧

The documentation in this section is for developers contributing to the core Snipe-IT package!

Consumers of the API should read the reference section for API documentation.

Before opening an issue to report a bug or request help, make sure you've checked the Common Issues and Getting Help pages.

Please refrain from submitting issues or pull requests generated by fully-automated tools. Maintainers reserve the right, at their sole discretion, to close such submissions and to block any account responsible for them.

Ideally, contributions should follow from a human-to-human discussion in the form of an issue.

Development Philosophy

If we had thought to write this out years ago, we would have created this document . We are not affiliated in any way with Godot, but their devs/documentation authors have nailed how we approach features and bugs in Snipe-IT. Even if you don't plan on contributing to Snipe-IT, it's well worth a read.

Developing on Snipe-IT

📘

New to Contributing?

That's fine! Lots of the contributors to Snipe-IT are first-timers. If you're a little confused on how to get started, be sure to check out How to Contribute to Open Source for an overview of good habits, and the Github documentation on how to create a Pull Request for the technical bits.

It can be scary at first, but don't worry - you'll do fine.

Please submit all pull requests to the snipe/snipe-it repository in the develop branch!

As you're working on bug-fixes or features, please break them out into their own feature branches and open the pull request against your feature branch. It makes it much easier to decipher down the road, as you open multiple pull requests over time, and makes it much easier for us to approve pull requests quickly.

If you don't have a feature in mind, but would like to contribute back to the project, check out the open issues and see if there are any you can tackle.

If you have a feature in mind that hasn't been asked for in Github Issues, please open an issue so that we can discuss how it should work so that it will benefit the entire community.

Setting Up a Dev Installation

The only real difference in setting Snipe-IT up for local development versus setting it up for production usage is the .env configuration files.

You’ll want to make sure you have the configuration files updated for whichever environment you’re in, which will most likely be local.

If your development, staging and production sites all run on the same server (which is generally a terrible idea), see this example of how to configure the app using environmental variables.

Switching from Production to Develop branches

If you have a functional Snipe-it install and would like it to be your Dev environment (Only recommended for new installs, not production sites) you will need to run the following commands: (Assuming you have already created a fork of snipe-it)

SSH

cd <install-dir>
git checkout develop
git remote rename origin upstream
git remote add origin https://github.com/YOUR_USERNAME/YOUR_FORK
git checkout -b origin/develop
curl -sS https://getcomposer.org/installer | php
php composer.phar install --prefer-source
git push origin develop

This will set up your git repository and push it to your own github account. After this, you may create your own branch for features or fixes.

It is recommended to edit your .env file as well to make the following changes.

.env

APP_ENV=developement
APP_DEBUG=true

Set up the debugbar

In dev mode, we use the fabulous Laravel Debugbar by barryvdh.

The profiler is enabled by default if you have debug set to true in your .env file. You certainly don’t have to use it, but it’s pretty handy for troubleshooting queries, seeing how much memory your pages are using, making sure your code isn't introducing n+1 queries, etc.

Database Considerations

Always make sure you're eager loading queries where possible, to avoid "N+1 query" issues with large data sets. The debugbar at the bottom of your development installation will show you the number of queries you're executing, which should alert you to any issues.

Purging the autoloader

If you’re doing any development on this, make sure you purge the auto-loader if you see any errors stating the new model you created can’t be found, etc, otherwise your new models won’t be grokked.

php composer.phar dump

Composer Update

In general, you wouldn't normally be running composer update, as that's usually something that can end up affecting sections of the app that aren't related to what you're working on. Plus it's pretty miserable overall, so we don't usually expect other folks go through that.

If you do find yourself in that position, however, and you find yourself running out of memory as composer is trying to reconcile dependencies, you can run:

Shell

php -d memory_limit=-1 $(which composer) update

This will allow you to increase the amount of memory composer is allowed to consume more memory while it's doing all of that heavy lifting.

If you do end up needing to install additional libraries for the feature you're working on, you'll want to make sure the PHP compatibility isn't going to break past our stated minimum required version. This can get tricky, because composer check-platform-reqs will only check whether or not your current system can work with the requirements, but doesn't really help you determine that nothing you're doing might break compatibility on other systems using (for example) a version of PHP that is lower than your own but still within the acceptable minimum requirements.

Shell

(composer show -t --no-ansi && composer show -s -t --no-ansi) | grep -o "\-\-\(ext-.\+\|php \).\+" | sort | uniq | cut -d- -f3-

Localization Support

When developing on Snipe-IT, please always use language strings (trans('path/to/file.string')) instead of regular text on any user-facing text, so that we can easily extend your changes out to the translation community.

You do not need to provide translated strings for all of the languages we support, only English (app/lang/en). We use CrowdIn for translation management by native speakers, so you only need to provide English strings. More info on translations available on the Translations page.

Code Comments

Snipe-IT uses phpDocumentor style docblocks. An example of the format that comment blocks should use is below.

PHP

/**
* A summary informing the user what the associated element does.
*
* A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
* and to provide some background information or textual references.
*
* @param string $myArgument With a *description* of this argument, these may also
*    span multiple lines.
*
* @return void
*/

For more information, check out the phpDocumentor documentation.

Testing

We use PHPUnit for testing. To run the full suite of tests:

php artisan test

To run just a particular test, use the filter option:

To php artisan test --filter=GroupStoreTest

in your project root.

Pull request guidelines

A good commit message should describe what changed and why. Snipe-IT uses semantic commit messages to streamline the release process and easily generate changelogs between versions.

Before a pull request can be merged, it must have a pull request title with a semantic prefix.

Examples of commit messages with semantic prefixes:

• Fixed #<issue number>: don't overwrite prevent_default if default wasn't prevented
• Added #<issue number>: add checkout functionality to assets

❗️

Make sure to also mention the issue number in the message body

You'll need to repeat yourself here, in the contents of your PR message - fixes #1234.

Please reference the issue or feature request your PR is addressing. Github will automatically link your PR to the issue, which makes it easier to follow the bugfix/feature path in the future.

Whenever possible, please provide a clear summary of what your PR does, both from a technical perspective and from a functionality perspective.

Screenshots and/or animated gifs are especially appreciated!

Database Migrations

All migrations should have an up() that creates the change and down() method that reverses it.

❗️

A Note on Enums

Please do not use enums as a field type. Doctrine doesn't handle them very well (it won't allow you to later modify ANY fields in a table that has a single enum), and it only causes problems down the line. Use a string field type instead.

If you HAVE to use an enum (again, don't), you will create a situation where any future migration that modifies a field on the table you've added the enum to will need to have this in the migration:

PHP

$platform = $em->getConnection()->getDatabasePlatform();
$platform->registerDoctrineTypeMapping('enum', 'string');

Contributor Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See the source on Github to read the current version of the Code of Conduct.