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.
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
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.
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.
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)
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.
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.
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.
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
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:
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.
(composer show -t --no-ansi && composer show -s -t --no-ansi) | grep -o "\-\-\(ext-.\+\|php \).\+" | sort | uniq | cut -d- -f3-
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.
Snipe-IT uses phpDocumentor style docblocks. An example of the format that comment blocks should use is below.
/** * 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.
We use Codeception and PHPUnit for acceptance and unit testing. To run Codeception tests, you'll need the PhantomJS node module installed. Start PhantomJS like this:
node_modules/.bin/phantomjs --webdriver=4444 --ignore-ssl-errors=true
Then you can run your Codeception tests in a separate SSH terminal, by running:
in your project root.
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
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!
All migrations should have an
up() that creates the change and
down() method that reverses it.
A Note on Enums
Please do not use
enumsas 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
stringfield 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:
$platform = $em->getConnection()->getDatabasePlatform(); $platform->registerDoctrineTypeMapping('enum', 'string');
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.
Updated over 1 year ago