User Tools

Site Tools


contributing_mappings

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
contributing_mappings [2019/08/12 22:11]
be.ing [Documenting the mapping]
contributing_mappings [2020/01/20 18:36]
hlzhs
Line 2: Line 2:
 The more choice users have for devices to use with Mixxx, the better. There are many DJ controllers on the market and most of them aren't very cheap. The Mixxx developers do not have resources to get every controller out there and map it, so the community generally relies on users to contribute mappings. We try to make mapping as easy as possible, but making a complete mapping typically takes some technical skill beyond what many users have. So, getting a controller that doesn'​t have a Mixxx mapping yet and making a mapping is a great way to contribute to Mixxx if you have some technical skill but may not know C++. The more choice users have for devices to use with Mixxx, the better. There are many DJ controllers on the market and most of them aren't very cheap. The Mixxx developers do not have resources to get every controller out there and map it, so the community generally relies on users to contribute mappings. We try to make mapping as easy as possible, but making a complete mapping typically takes some technical skill beyond what many users have. So, getting a controller that doesn'​t have a Mixxx mapping yet and making a mapping is a great way to contribute to Mixxx if you have some technical skill but may not know C++.
  
-Controller mappings are written in [[MIDI controller mapping file format|XML]] and [[MIDI scripting|JavaScript]]. While mappings can be made with just XML, most controllers will require some JavaScript to make a complete mapping. Some controllers will require a mapping mostly or completely written in JavaScript. Both XML and JavaScript are fairly straightforward and easy to learn. Using JavaScript to map your controller could be a good introduction to programming. If you are unfamiliar with MIDI, refer to the [[MIDI Crash Course]] page.+Controller mappings are written in [[MIDI controller mapping file format|XML]] and [[MIDI scripting|JavafixedScript]]. While mappings can be made with just XML, most controllers will require some JavaScript to make a complete mapping. Some controllers will require a mapping mostly or completely written in JavaScript. Both XML and JavaScript are fairly straightforward and easy to learn. Using JavaScript to map your controller could be a good introduction to programming. If you are unfamiliar with MIDI, refer to the [[MIDI Crash Course]] page.
  
 For someone with prior programming experience, writing an initial mapping for a controller can be done in a few days. However, you will likely want to change some of your initial design decisions as you use the mapping, especially if you do not have much experience using DJ controllers. Refining the design is a gradual process that takes experimentation and revising. You are encouraged to seek feedback from users on the [[http://​mixxx.org/​forums/​viewforum.php?​f=7|Mixxx forum]] as you develop the mapping. For someone with prior programming experience, writing an initial mapping for a controller can be done in a few days. However, you will likely want to change some of your initial design decisions as you use the mapping, especially if you do not have much experience using DJ controllers. Refining the design is a gradual process that takes experimentation and revising. You are encouraged to seek feedback from users on the [[http://​mixxx.org/​forums/​viewforum.php?​f=7|Mixxx forum]] as you develop the mapping.
Line 14: Line 14:
 We use Git for coordinating Mixxx development. Git is software that helps keep track of changes in files. Before you start working on your mapping, it is recommended (but not necessary) to set up git on your computer. Using git will help you keep track of your progress on the mapping and help Mixxx developers review it. If you have already finished your mapping, that's okay, just add your finished mapping files in one commit. Start by creating a [[http://​github.com/​|GitHub]] account, [[https://​github.com/​mixxxdj/​mixxx|forking Mixxx]], and cloning your forked git repository onto your computer. We use Git for coordinating Mixxx development. Git is software that helps keep track of changes in files. Before you start working on your mapping, it is recommended (but not necessary) to set up git on your computer. Using git will help you keep track of your progress on the mapping and help Mixxx developers review it. If you have already finished your mapping, that's okay, just add your finished mapping files in one commit. Start by creating a [[http://​github.com/​|GitHub]] account, [[https://​github.com/​mixxxdj/​mixxx|forking Mixxx]], and cloning your forked git repository onto your computer.
  
-Make a new git branch (run ''​git checkout -b new_branch_name''​ from within your git repository). Make changes to your mapping and commit them when your changes work. Before making any commits, configure git to use your name and email in your commits. See the [[Using Git]] wiki page for more information. Please prefix your git commit messages with the name of your controller so others can easily tell what the commits are for after your changes are merged. For example, a good commit message could look like:\\+Usually, ​new mappings can be released as part of bugfix releases. Hence, you should usually use the current stable release ​branch (e.g. ''​2.2''​) instead of the `master` branch as a starting point for your new mapping branch. You run ''​git checkout -b new_branch_name ​2.2''​ from within your git repository ​to that. If you're making use of unreleased features that are only present in ''​master'',​ you can also use ''​master''​ as base branch instead (run ''​git checkout -b new_branch_name master''​). 
 + 
 +Make changes to your mapping and commit them when your changes work. Before making any commits, configure git to use your name and email in your commits. See the [[Using Git]] wiki page for more information. Please prefix your git commit messages with the name of your controller so others can easily tell what the commits are for after your changes are merged. For example, a good commit message could look like:\\
 ''​Hercules P32: push browse encoder to maximize/​minimize library''​ ''​Hercules P32: push browse encoder to maximize/​minimize library''​
  
Line 26: Line 28:
 ==== Submitting your mapping for review ==== ==== Submitting your mapping for review ====
  
-When your mapping is complete, [[#​Documenting the mapping|documented on the wiki]], and you are ready to submit your mapping for inclusion in Mixxx, make a pull request on GitHub. Make sure that the target branch of mixxxdj/​mixxx for your pull request is the branch that you started your git branch from (if it isn't, you'll see commits unrelated to your mapping included in your pull request).+When your mapping is complete, [[#​Documenting the mapping|documented on the wiki]], and you are ready to submit your mapping for inclusion in Mixxx, make a pull request on GitHub. Make sure that the target branch of mixxxdj/​mixxx for your pull request is the branch that you started your git branch from (if it isn't, you'll see commits unrelated to your mapping included in your pull request). If you accidently started from the wrong branch when working on your mapping, you can also  [[https://​mixxx.org/​wiki/​doku.php/​using_git#​targeting_another_base_branch|rebase and change the target of your PR]].
  
 Although we try not to let pull requests linger without review, keep in mind that Mixxx is a volunteer project and someone will review your pull request when they have time available. Mappings will be reviewed to check that they follow the [[#design guidelines]],​ [[#coding conventions for JavaScript]],​ [[#coding conventions for XML]], to check that the mapping is [[#​documenting the mapping|documented well on the wiki]], and to look for potential bugs. To update your mapping in response to reviewers'​ comments, edit your file(s), make a new git commit, and push your git commit. The new commit(s) will automatically show up in the pull request. Although we try not to let pull requests linger without review, keep in mind that Mixxx is a volunteer project and someone will review your pull request when they have time available. Mappings will be reviewed to check that they follow the [[#design guidelines]],​ [[#coding conventions for JavaScript]],​ [[#coding conventions for XML]], to check that the mapping is [[#​documenting the mapping|documented well on the wiki]], and to look for potential bugs. To update your mapping in response to reviewers'​ comments, edit your file(s), make a new git commit, and push your git commit. The new commit(s) will automatically show up in the pull request.
Line 127: Line 129:
   * Always use brackets for ''​if''​ statements. Put the opening ''​{''​ on the same line as the conditional expression and the closing bracket ''​}''​ on its own line.   * Always use brackets for ''​if''​ statements. Put the opening ''​{''​ on the same line as the conditional expression and the closing bracket ''​}''​ on its own line.
   * Put ''​else''​ statements on the same line as the previous closing ''​}''​   * Put ''​else''​ statements on the same line as the previous closing ''​}''​
-  * For defining functions in object literals, put the opening ''​function (parameters) {''​ line on the same line as the property name, then indent the function body 4 spaces. Put the closing ''​}''​ at the same indention level as the object properties.+  * For defining functions in object literals, put the opening ''​function(parameters) {''​ line on the same line as the property name, then indent the function body 4 spaces. Put the closing ''​}''​ at the same indention level as the object properties.
   * Put '',''​ after the last property of object literals to avoid errors when adding more properties in the future.   * Put '',''​ after the last property of object literals to avoid errors when adding more properties in the future.
   * All code lines that need it must end with '';''​   * All code lines that need it must end with '';''​
Line 139: Line 141:
  
 var anotherObject = { var anotherObject = {
-    someFunction:​ function (parameter) {+    someFunction:​ function(parameter) {
         return parameter++;​         return parameter++;​
     },     },
-    anotherFunction:​ function (parameter) {+    anotherFunction:​ function(parameter) {
         return parameter--;​         return parameter--;​
     },     },
 } }
  
-ShinyObject.someMethod = function (someParameter) {+ShinyObject.someMethod = function(someParameter) {
     var someVariable = someParameter + 2;     var someVariable = someParameter + 2;
     if (someVariable === 5) {     if (someVariable === 5) {
Line 157: Line 159:
 </​code>​ </​code>​
  
-==== Code checking ​tools ==== +==== Automated code checking ​(linting) ​==== 
-We use the automated code testing tools [[http://jshint.com/​|JSHint]] and [[http://​jsbeautifier.org/|JSBeautifier]] that check for bad practices in JavaScript code. You can copy and paste your JS code onto those web pages to use them or you can use them locally ​on your computer ​with Node.js. Using these tools is not for making your coding skill look bad; they are to help you make your code even betterIf you use these, you will already have the basics taken care of when you submit a pull request.+We use the automated code checking tool [[https://eslint.org/|eslint]] that looks for bad practices ​and potential problems ​in JavaScript code. The Mixxx repository contains a configuration file, so that you can easily ​use it to check the code of JavaScript files on your computer ​by running ''​eslint path/​to/​my-controller-script.js''​Some IDEs or editors like [[https://code.visualstudio.com/​|Visual Studio Code]] or [[https://​www.vim.org/​|(Neo-)Vim]] with the [[https://​github.com/​dense-analysis/​ale|ALE]] plugin should even pick it up automatically and warn you about potential problems while you are typing.
  
-JSHint ​can also be helpful if Mixxx says there is an error in your JavaScript code but Mixxx'​s error message does not make it clear what the issue is.+Using this tool is not for making your coding skill look bad; it is to help you make your code even better. If you use it, you will already have the basics taken care of when you submit a pull request. 
 +Running eslint ​can also be helpful if Mixxx says there is an error in your JavaScript code but Mixxx'​s error message does not make it clear what the issue is. Some common formatting issues can also be fixed automatically by using the ''​--fix''​ parameter (run ''​eslint --fix path/​to/​my-controller-script.js''​).
  
-All Javascript files for Mixxx must start with header to make sure JSHint doesn'​t generate errors for missing variables: 
-<​code>​ 
-////////////////////////////////////////////////////////////////////////​ 
-// JSHint configuration ​                                              // 
-////////////////////////////////////////////////////////////////////////​ 
-/* global engine ​                                                     */ 
-/* global script ​                                                     */ 
-/* global print                                                       */ 
-/* global midi                                                        */ 
-//////////////////////////////////////////////////////////////////////// ​ 
-</​code>​ 
  
 ===== Coding conventions for XML ===== ===== Coding conventions for XML =====
contributing_mappings.txt · Last modified: 2020/03/24 07:55 by hlzhs