Skip to content

Latest commit

 

History

History
211 lines (151 loc) · 7.97 KB

CONTRIBUTING.md

File metadata and controls

211 lines (151 loc) · 7.97 KB

Contributing to SmallServerAdmin

Thanks for taking the time to contribute!

The following is a set of guidelines for contributing to SmallServerAdmin.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Found an Issue?

If you find a bug in the source code, you can help us by submitting an issue to our GitHub Repository. Even better you can submit a Pull Request with a fix.

Want a new Module or Feature?

You can request a new module or feature by submitting an issue to our GitHub Repository.

Please note:

  • Major Changes that you wish to contribute to the project should be discussed.
  • Small Changes can be crafted and submitted to the GitHub Repository as a Pull Request.

Code Contributions

The project welcomes new contributors.

To get started, fork the SmallServerAdmin on GitHub and check out your copy locally.

Make your changes, in accordance with our rules and recommendations.

Make sure that your changes are working properly.

Commit and Push your changes.

Send Pull Request.

Please, before writing code, pay attention to requests queue and see SmallServerAdmin version in the dev branch.

Coding Rules

To ensure consistency throughout the source code and to work properly it is recommended to follow the rules:

  • All public classes, methods and properties must be documented;
  • Use two spaces for indentation;
  • Server-side code must be placed in the SmallServerAdmin;
    • For server-side code use namespaces:
      • for API: Api (examples: #1, #2);
      • for Models: Models (examples: #1, #2);
      • for pages: ModuleName (examples: #1, #2);
    • Use SSH class ot the /ssh/api.php to work with SSH;
    • For new modules, do not forget to create a README and CHANGELOG files;
    • Each module should have a version number in the following format: Major.Minor.Changes. For example: 1.0.0;
    • Recommended to work with the API using client-side code;
    • Watch out for encoding files. Use UTF-8 without BOM. This can be critical for PHP;
  • Client-side code must be placed in the FrontEndScripts;
    • Use TypeScript;
    • Recommended to use AngularJS;
    • Compiled code must be placed in the folder ../SmallServerAdmin/Content (files: compiled.js and compiled.min.js);
    • For client-side code use namespaces:
      • SmallServerAdmin - root namespace;
      • SmallServerAdmin.Controllers - controllers;
      • SmallServerAdmin.Filters - custom filters;
      • SmallServerAdmin.Models - models;
    • Recommended to use the camel style. The first word with capital letters. For example: TheNewBestName;
    • Use prefix:
      • I* - for interfaces. For example: ISelectPath;
    • Use suffix:
      • *Controller - for controllers. For example: UserListController;
    • Use ApiRequest class to work with WebAPI;

Structure of the project

Introduction

The solution consists of two projects: SmallServerAdmin and FrontEndScripts.

SmallServerAdmin - the main project. It contains client pages and classes to interact with a server.

FrontEndScripts - contains client-side code.

SmallServerAdmin

The project has a strict structure.

At the root folder located modules.

In the same folder can be only one module.

The module name is the name of the folder.

The following shows the structure of the project files:

SmallServerAdmin
-- Content - styles, fonts, images and client-side scripts
-- Controls - user controls of the SSA
-- Layouts - master pages (templates)
-- Libs - additional server-side libraries
-- servers - contains configuration files connected servers
-- .version - current version of the panel
-- api.php - the main file for API
-- config.php - config of the WebForms.PHP
-- global.json and global.*.json - localization resources
-- global.php - global handler (WebForms.PHP)
-- index.php and index.html.php - main page
-- ssa.config.php - config of SmallServerAdmin
-- any module
---- api.php - methods of API
---- index.php (+index.html.php) - main page of module
---- menu.php - view of the module in the navigation menu (optional)
---- widget.php - widget to display on the panel main page (optional)
---- any files and folders (optional)

Each module should have its own api.php file. This file must contain the public API methods.

Call API methods through api.php file located in the root directory.

As a rule, work with the API is through the client-side code.

FrontEndScripts

Client-side code written in TypeScript for AngularJS.

FrontEndScripts
-- Controllers - controllers
-- Filters - custom filters for AngularJS
-- Interfaces - additional interfaces
-- libs - additional libraries
-- Models - models (yet in a heap)
-- typings - type definitions for TypeScript and Visual Studio
-- _app.ts - main application class
-- ApiRequest.ts - API request helper
-- bundleconfig.json - building rules (for VS2015)
-- compiled.js.bundle - building rules (for VS2013)

Software

You can use any handy software. It will be nice if you include your changes to SmallServerAdmin.phpproj, FrontEndScripts.csproj, compiled.js.bundle, bundleconfig.json and compilerconfig.json.

The project is written in Visual Studio 2015.

Visual Studio 2013 (Professional or Ultimate)

Visual Studio 2015

And also required TypeScript (v1.5-1.8) and SCSS.

To manage nesting files recommended the extension File Nesting.

PHP

For PHP required php_ssh2.dll.

Download Win32 SSH2 PECL extension and extract php_ssh2.dll to C:\Program Files (x86)\IIS Express\PHP\v5.5\ext, and libssh2.dll to C:\Program Files (x86)\IIS Express\PHP\v5.5.

Open C:\Program Files (x86)\IIS Express\PHP\v5.5\php.ini and add: extension=php_ssh2.dll to [ExtensionList]:

[ExtensionList]
; ... other extinsions
extension=php_ssh2.dll

NOTE: Restart IIS, if is started.

ATTENTION: At the time of this writing, SSH no problem to work with PHP 5.5. In PHP 5.6 and PHP 7 had problems.

For more information please see PHP Manual.

To test it is recommended to use a virtual machines of VirtualBox or VMWare.