Skip to content

Latest commit

 

History

History
59 lines (49 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

59 lines (49 loc) · 5.43 KB
Raw

Contributing to Vitrine

Hi there! If you're reading this, you probably want to contribute to Vitrine, I first want to thank you for that! My name is Paul, I'm the creator and the main developper of Vitrine. This guide is here to help you understaning the philosophy of the project, getting you started and giving you guidelines for further contributions. Note that this guide is likely to change in the future, so feel free to check again this file at some point.

As you probably already know it, Vitrine is using web technologies to run, the fundation of the project is the Electron framework, using both Chromium and Node.js APIs. We're also using TypeScript instead of pure JavaScript in order to have a more stable and safe code.

Getting Vitrine compiling and running

The first step to get Vitrine running is to install its dependencies. We're using Yarn as a packages manager, so you just need to clone the repository and run yarn install.

Vitrine is using custom Node.js native addons, written in C++, which need to be compiled using node-gyp. For the moment, Vitrine is only running on Windows and Linux, which means that the C++ addons can be compiled using different ways :

  • Visual C++ Build Tools on Windows : you need to download and install Windows-Build-Tools
  • Python 2.7 on Linux

Vitrine is using multiple APIs to work (IGDB, Steam, Discord...). This keys are obviously not stored in the public repo, but a ciphered version is present. To build Vitrine, you need an environment variable called VITRINE_KEY. If you want to work on the project, feel free to contact me to retrieve the key! Then, run yarn keys:decrypt to build the keys.hh file that will contain clear APIs keys. Then just hit with a yarn run:app and you're ready to go!

Writing code

Few things on how we code here:

  • We are using TSLint to format the code, so when you are writing make sure to run yarn run lint-app to see if your code is compliant to the style guide.
  • If you don't manually format your code, TSLint will automatically fix it at precommit.
  • We use Mocha along with Chai to write tests. For the moment, tests are not fully provided, so feel free to write some for existing pieces of code.
  • We are using WebStorm as IDE. You're free to use any editor you want; we are using it because it has extensions for Mocha and TSLint.

Project file structure

Vitrine isn't built using boilerplate, so the the file structure is free and tweakable:

  • /config: used to store config used by Vitrine, copied within build
    • /cache: used to store different caches used by the application to optimize queries (IGDB data from potential games and Steam app IDs). Shouldn't be edited
    • /lang: here are the files for i18n, just regular JSON files with a key value system
    • /modules_config.json: static information that aren't supposed to change, like emulators list or Origin registry keys
    • /vitrine_config.json: configuration edited directly from the software by the used, persistently stored here
  • /dist: the built software is stored here
  • /games: here lies what everything is about! Every game is stored in a folder using a UUID and containing a config.json, and potentially a cover.XXXXXXXX.jpg and a background.XXXXXXXX.jpg (XXXXXXXX is a unique tag used for caching)
  • /keys: here is the encrypted file used to store ciphered keys for the APIs used in the application.
  • /modules: the build native Node.js modules (.node files) are stored here
  • /node_modules: you already know what's is here
  • /public: transpiled code lies here. client.html and loader.html are generated by webpack-html-plugin
    • /img: images needed for the packaging process stored here
  • /scripts: nothing really interesting, just some scripts used for build process
  • /sources: that's pretty much what you're looking for, so let's begin, shall we?
    • /client: sources executed in the rendered process of Electron are located here
      • /app: the React app of Vitrine client is stored here. It has a simple React/Redux app structure (actions, components, containers, reducers folders)
      • /defs: here are located special TypeScript definitions (like the ones used to import custom files in TypeScript) as .d.ts files
      • /resources: every asset used by the client that is not source code is located here. They will by directly loaded into client.js and loader.js when transpiling. The less folder (hosting the stylesheets used by the client) is structured using Semantic UI Less
    • /models: pieces of code used both on the client and the server-side
    • /modules: C++ source code for native Node.js modules. Each module folder contains a build and a srcs folder, a binding.gyp (containing information about module build) and a TypeScript file which should be used to import the module into server source code
    • /server: sources executed in the main process of Electron are located here
      • /api: the source code here depends on a certain support to work (platform or file format) and should be only used as an interface by the other files (specific implementation hidden)
      • /crawlers: the list of the games crawlers is located here
  • /test: pretty self-explanatory
  • /webpack: here are the different configs used by Webpack to build Vitrine