Development environment and conventions

What do you need to know to contribute

• Well, git obviously 😄
• Node.js and npm
• TypeScript, HTML and CSS knowledge will be useful
• Know your way around the Browser debugging tools
• Most of what you need to know about browser extensions is described below
• The English language. You will have noticed by now, that we decided to keep everything, be it code, commit messages or documentation, in English. Even though the extension is only used by the German CS community, the contents of this repository could be helpful to anyone around the world. But only in English. 😃

Setup your flashkill development environment

• Fork the flashkillapp/flashkill repository to your GitHub account
• Clone the GitHub repository
• Run npm ci and npm run watch in the flashkill repository to build the extension
• You are likely already running the production version of the extension in your main browser. To have a comparison all the time and to distinguish between the development and production versions more easily, we suggest to use a different browser for development. If Chrome is your main browser, consider downloading Chromium but make sure that the extension also runs in Firefox before you commit your changes.
• The directory that you should load as an unpacked extension into your browser is the dist directory. In Chrome you simply choose the directory, in Firefox you choose the manifest.json file as the source. For detailed instructions please checkout this wiki post.

Navigating the extension code

The setup might look a bit elaborate if this is your first time working with a bundler. The code that you are most likely to edit lies in the src directory. There are only very few files in the dist directory that are not generated and they mostly control the popup window that appears when you click on the flashkill logo among your browser extensions.

But then there is also the heart of the browser extension, the manifest.json in the dist directory.

manifest.json

This file defines the extension, giving it a name, a version, listing its permissions and telling the browser when to execute which script. There are two different types of scripts defined, the background and the content scripts.

background scripts

These scripts are loaded each time you visit one of the pages the extension has permissions for. On their own these scripts don't do anything with the extension because they don't even have access to what is going on in your browser window. We mainly use these scripts to define listeners that will for example request other 99Damage pages and provide their content. You can read more about background scripts here.

All background scripts that support functionality on different pages of 99Damage, are bundled into the same background.js file.

"background": {
  "scripts": [
    "background.js"
  ]
}

content scripts

The content scripts on the other hand have access to the DOM and it is in here where we add elements such as the FACEIT-Elo and FACEIT-Level images into the page. You can see that they are paired with a match string, which describes the URLs this script should be loaded on.

Note that the script is called index.js here but it actually originates from the content.ts files in the page directories.

"content_scripts": [
  {
    "matches": ["https://liga.99damage.de/leagues/teams/*-*"],
    "js": [
      "content/team-page/index.js"
    ]
  }
]

The src directory

The directory names should be rather self explanatory.

• components: We use web components based on LitElement for all complex UI additions
• features: As the name suggests, all flashkill features are implemented here. This is where the content and background scripts for the different pages lie. For each page there is a single content.ts page which actually calls the feature initialization methods from the different feature scripts. When implementing a new feature make sure to execute it in the content.ts file. When adding the first feature for a new page, make sure to include the content, background, index files in the webpack.config.js and the manifest.json.
• model: Holds interface definitions
• util: Functions that are not feature or page specific

Tools

We recommend using Visual Studio Code to develop this extension and include recommended extensions and project wide code snippets for a better development experience.

What to contribute

We keep track of all the known issues on this board. By looking at the issues on the board you get an overview on what we already filtered out to be issues to be worked on and usually some clear description of what has to be done to fix the issue. We even mark issues with good first issue if we consider an issue to be solvable without too much knowledge about the extension's code.

You are of course also welcome to just code away and implement your own ideas and enhancements into the extension. Please let us know if you came up with something amazing. 😮

Commit your changes

• If you start developing on a new issue, it might be a good idea to leave a comment, that you are looking into this and keep an eye on the conversation going forward.
• Make sure you have the latest version of flashkillapp/flashkill/master and branch off from it with git checkout -b [issue number]-short-description-of-the-issue.
• After you made changes to your code make sure that all our checks still pass. You can check this locally with npm run lint, npm run type-check and npm run build.
• If everything looks fine, commit your changes with a descriptive commit message.
• It's good practice to make your branch a remote branch as soon as you do your first commit. To do so use git push -u origin [issue number]-short-description-of-the-issue. This will ensure that all future pushes on this local branch will go to the remote branch for this feature.
• If you are done and have tested the extension, you can create a pull request to the flashkillapp/flashkill repository. Visit https://github.com/[your github username]/flashkill/branches and click New pull request, on the remote branch you were working on. Make sure that you select base repository: flashkillapp/flashkill and base: master.
• Give the pull request some short descriptive title and use the body to describe on a high level what changes you made. Be sure to include something like "Resolves #13" in the body if you worked on resolving issue 13.
• After you created the pull request, we will take a look at your changes and hopefully be able to integrate them into the production version of the extension. 😃