Cleanup and improve build docs

This commit is contained in:
Dane Everitt 2021-03-26 09:50:46 -07:00
parent a072b9c5be
commit 9a5486c0aa
No known key found for this signature in database
GPG key ID: EEA66103B3D71F53
7 changed files with 64 additions and 125 deletions

View file

@ -1,16 +0,0 @@
<?php
use Sami\Sami;
use Symfony\Component\Finder\Finder;
$iterator = Finder::create()
->files()
->name('*.php')
->in($dir = __DIR__ . '/app');
return new Sami($iterator, array(
'title' => 'Pterodactyl',
'build_dir' => __DIR__ . '/.sami/build',
'cache_dir' => __DIR__ . '/.sami/cache',
'default_opened_level' => 2,
));

View file

@ -1,7 +0,0 @@
preset: laravel
risky: false
disabled:
- concat_without_spaces
enabled:
- concat_with_spaces
- no_unused_imports

View file

@ -1,36 +0,0 @@
language: php
dist: trusty
git:
depth: 3
quiet: true
matrix:
fast_finish: true
allow_failures:
- env: TEST_SUITE=Coverage
env:
matrix:
- TEST_SUITE=Unit
- TEST_SUITE=Coverage
- TEST_SUITE=Integration
php:
- 7.4
sudo: false
cache:
directories:
- $HOME/.composer/cache
services:
- mysql
before_install:
- mysql -e 'CREATE DATABASE IF NOT EXISTS travis;'
before_script:
- echo 'opcache.enable_cli=1' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
- cp .env.travis .env
- travis_retry composer install --no-interaction --prefer-dist --no-suggest
script:
- if [ "$TEST_SUITE" = "Unit" ]; then vendor/bin/phpunit --bootstrap vendor/autoload.php tests/Unit; fi;
- if [ "$TEST_SUITE" = "Coverage" ]; then vendor/bin/phpunit --bootstrap vendor/autoload.php --coverage-clover coverage.xml tests/Unit; fi;
- if [ "$TEST_SUITE" = "Integration" ]; then vendor/bin/phpunit tests/Integration; fi;
notifications:
email: false
after_success:
- bash <(curl -s https://codecov.io/bash)

View file

@ -1,10 +1,13 @@
# Local Development # Local Development
Pterodactyl is now powered by Vuejs and Tailwindcss and uses webpack at its core to generate compiled assets. Release Pterodactyl is now powered by React, Typescript, and Tailwindcss using webpack at its core to generate compiled assets.
versions of Pterodactyl will include pre-compiled, minified, and hashed assets ready-to-go. Release versions of Pterodactyl will include pre-compiled, minified, and hashed assets ready-to-go.
However, if you are interested in running custom themes or making modifications to the Vue files you'll need a build However, if you are interested in running custom themes or making modifications to the React files you'll need a build
system in place to generate these compiled assets. To get your environment setup, you'll first need to install at least Nodejs system in place to generate these compiled assets. To get your environment setup you'll need at minimum:
`8`, and it is _highly_ recommended that you also install [Yarn](https://yarnpkg.com) to manage your `node_modules`.
* Node.js 12
* [Yarn](https://classic.yarnpkg.com/lang/en/) v1
* [Go](https://golang.org/) 1.15.
### Install Dependencies ### Install Dependencies
```bash ```bash
@ -12,17 +15,19 @@ yarn install
``` ```
The command above will download all of the dependencies necessary to get Pterodactyl assets building. After that, its as The command above will download all of the dependencies necessary to get Pterodactyl assets building. After that, its as
simple as running the command below to generate assets while you're developing. simple as running the command below to generate assets while you're developing. Until you've run this command at least
once you'll likely see a 500 error on your Panel about a missing `manifest.json` file. This is generated by the commands
below.
```bash ```bash
# build the compiled assets for development # Build the compiled set of assets for development.
yarn run build yarn run build
# build the assets automatically when files are modified # Build the assets automatically as they are changed. This allows you to refresh
# the page and see the changes immediately.
yarn run watch yarn run watch
``` ```
### Hot Module Reloading ### Hot Module Reloading
For more advanced users, we also support 'Hot Module Reloading', allowing you to quickly see changes you're making For more advanced users, we also support 'Hot Module Reloading', allowing you to quickly see changes you're making
to the Vue template files without having to reload the page you're on. To Get started with this, you just need to the Vue template files without having to reload the page you're on. To Get started with this, you just need
@ -37,21 +42,22 @@ is the `--host` flag, which is required and should point to the machine where th
The second is the `PUBLIC_PATH` environment variable which is the URL pointing to the HMR server and is appended to all of The second is the `PUBLIC_PATH` environment variable which is the URL pointing to the HMR server and is appended to all of
the asset URLs used in Pterodactyl. the asset URLs used in Pterodactyl.
#### Vagrant #### Development Environment
If you want to use HMR with our Vagrant image, you can use `yarn run v:serve` as a shortcut for the correct parameters. If you're using the [`pterodactyl/development`](https://github.com/pterodactyl/development) environments, which are
In order to have proper file change detection you can use the [`vagrant-notify-forwarder`](https://github.com/mhallin/vagrant-notify-forwarder) to notify file events from the host to the VM. highly recommended, you can just run `yarn run serve` to run the HMR server, no additional configuration is necessary.
```sh
vagrant plugin install vagrant-notify-forwarder
vagrant reload
```
### Building for Production ### Building for Production
Once you have your files squared away and ready for the live server, you'll be needing to generate compiled, minified, and Once you have your files squared away and ready for the live server, you'll be needing to generate compiled, minified,
hashed assets to push live. To do so, run the command below: and hashed assets to push live. To do so, run the command below:
```bash ```bash
yarn run build:production yarn run build:production
``` ```
This will generate a production ready `bundle.js` and `bundle.css` as well as a `manifest.json` and store them in This will generate a production JS bundle and associated assets, all located in `public/assets/` which will need to
the `/public/assets` directory where they can then be access by clients, and read by the Panel. be uploaded to your server or CDN for clients to use.
### Running Wings
To run `wings` in development all you need to do is set up the configuration file as normal when adding a new node, and
then you can build and run a local version of Wings by executing `make debug` in the Wings code directory. This must
be run on a Linux VM of some sort, you cannot run this locally on macOS or Windows.

View file

@ -1,44 +1,55 @@
# Contributing # Contributing
We're glad you want to help us out and make this panel the best that it can be! We have a few simple things to follow when making changes to files and adding new features. We're glad you want to help us out and make this panel the best that it can be! We have a few simple things to follow
when making changes to files and adding new features.
### Development Environment
Please check the [`pterodactyl/development`](https://github.com/pterodactyl/development) repository for a Vagrant &
Docker setup that should run on most macOS and Linux distributions. In the event that your platform is not supported
you're welcome to open a PR, or just take a look at our setup scripts to see what you'll need to successfully develop
with Pterodactyl.
#### Building Assets
Please see [`BUILDING.md`](https://github.com/pterodactyl/panel/blob/develop/BUILDING.md) for details on how to actually
build and run the development server.
### Project Branches ### Project Branches
This section mainly applies to those with read/write access to our repositories, but can be helpful for others. This section mainly applies to those with read/write access to our repositories, but can be helpful for others.
The `develop` branch should always be in a runnable state, and not contain any major breaking features. For the most part, this means you will need to create `feature/` branches in order to add new functionality or change how things work. When making a feature branch, if it is referencing something in the issue tracker, please title the branch `feature/PTDL-###` where `###` is the issue number. The `develop` branch should always be in a runnable state, and not contain any major breaking features. For the most
part, this means you will need to create `feature/` branches in order to add new functionality or change how things
work. When making a feature branch, if it is referencing something in the issue tracker, please title the branch
`feature/PTDL-###` where `###` is the issue number.
Moving forward all commits from contributors should be in the form of a PR, unless it is something we have previously discussed as being able to be pushed right into `develop`. All new code should contain tests to ensure their functionality is not unintentionally changed down the road. This
is especially important for any API actions or authentication based controls.
All new code should contain unit tests at a minimum (where applicable). There is a lot of uncovered code currently, so as you are doing things please be looking for places that you can write tests. ### The CHANGELOG
You should not make any changes to the `CHANGELOG.md` file during your code updates. This is updated by the maintainers
### Update the CHANGELOG at the time of deployment to include the relevant changes that were made.
When adding something that is new, fixed, changed, or security-related for the next release you should be adding a note to the CHANGELOG. If something is changing within the same version (i.e. fixing a bug introduced but not released) it should _not_ go into the CHANGELOG.
### Code Guidelines ### Code Guidelines
We are a `PSR-4` and `PSR-0` compliant project, so please follow those guidelines at a minimum. In addition, StyleCI runs on all of our code to ensure the formatting is standardized across everything. When a PR is made StyleCI will analyze your code and make a pull to that branch if necessary to fix any formatting issues. This project also ships with a PHP-CS configuration file and you are welcome to configure your local environment to make use of that. We are a `PSR-4` and `PSR-0` compliant project, so please follow those guidelines at a minimum. In addition we run
`php-cs-fixer` on all PRs and releases to enforce a consistent code style. The following command executed on your machine
should show any areas where the code style does not line up correctly.
All class variable declarations should be in alphabetical order, and constructor arguments should be in alphabetical order based on the classname. See the example below for how this should look, or check out any of the `app/Service` files for examples. ```
vendor/bin/php-cs-fixer fix --dry-run --diff --diff-format=udiff --config .php_cs.dist
```php
class ProcessScheduleService
{
protected $repository;
protected $runnerService;
public function __construct(RunTaskService $runnerService, ScheduleRepositoryInterface $repository)
{
$this->repository = $repository;
$this->runnerService = $runnerService;
}
``` ```
### Responsible Disclosure ### Responsible Disclosure
This is a fairly in-depth project and makes use of a lot of parts. We strive to keep everything as secure as possible and welcome you to take a look at the code provided in this project yourself. We do ask that you be considerate of others who are using the software and not publicly disclose security issues without contacting us first by email. This is a fairly in-depth project and makes use of a lot of parts. We strive to keep everything as secure as possible
and welcome you to take a look at the code provided in this project yourself. We do ask that you be considerate of
others who are using the software and not publicly disclose security issues without contacting us first by email.
We'll make a deal with you: if you contact us by email and we fail to respond to you within a week you are welcome to publicly disclose whatever issue you have found. We understand how frustrating it is when you find something big and no one will respond to you. This holds us to a standard of providing prompt attention to any issues that arise and keeping this community safe. We'll make a deal with you: if you contact us by email and we fail to respond to you within a week you are welcome to
publicly disclose whatever issue you have found. We understand how frustrating it is when you find something big and
no one will respond to you. This holds us to a standard of providing prompt attention to any issues that arise and
keeping this community safe.
If you've found what you believe is a security issue please email us at `support@pterodactyl.io`. If you've found what you believe is a security issue please email `dane åt pterodactyl døt io`.
### Where to find Us ### Contact Us
You can find us in a couple places online. First and foremost, we're active right here on Github. If you encounter a bug or other problems, open an issue on here for us to take a look at it. We also accept feature requests here as well. You can find us in a couple places online. First and foremost, we're active right here on Github. If you encounter a
bug or other problems, open an issue on here for us to take a look at it. We also accept feature requests here as well.
You can also find us on [Discord](https://pterodactyl.io/discord). In the event that you need to get in contact with us privately feel free to contact us at `support@pterodactyl.io`. Try not to email us with requests for support regarding the panel, we'll probably just direct you to our Discord. You can also find us on [Discord](https://discord.gg/pterodactyl).

View file

@ -1,14 +0,0 @@
# Pterodactyl Panel Contributors
This panel would not be possible without the support of our wonderful community of
developers who provide code enhancements, new features, and bug fixes to make this panel
the best that is can be. You can view a full listing of contributors [here](https://github.com/Pterodactyl/Panel/graphs/contributors).
Dane Everitt [@DaneEveritt](https://github.com/Pterodactyl/Panel/commits?author=DaneEveritt)
Dylan Seidt [@DDynamic](https://github.com/Pterodactyl/Panel/commits?author=DDynamic)
[@nikkiii](https://github.com/Pterodactyl/Panel/commits?author=nikkiii)
# Get Involved
See our `CONTRIBUTING.md` document for information on how to get started. Once you've submitted some code feel free to
modify this file and add your name to the list. Please follow the format above for your name and linking to your contributions.

View file

@ -1,5 +0,0 @@
coverage:
status:
project: off
patch: off
comment: false