Skip to content

Latest commit

 

History

History
125 lines (82 loc) · 9.12 KB

CONTRIBUTING.md

File metadata and controls

125 lines (82 loc) · 9.12 KB
Raw

Contributing

Contributions are welcome.

To report bugs, request new features, or share your ideas, feel free to open issues or discussion. You can also send an email to [email protected] if you are not familiar with GitHub.

For direct contributions, see the following guidelines.

Contributing a tool

  1. Fork this repo and clone locally. If you have forked previously, sync to get the latest changes.

  2. Add a script TOOL_ID.js in simulator/js/objs, where TOOL_ID is the id of the new tool, and write the code there. See the README there for a correspondence between the id with the name of the existing tools on the toolbar.

  3. Add a script tag in simulator/index.html for the new tool.

  4. Add the locale strings for the tool to simulator/locales/en.js:

    • toolname_TOOL_ID: the label on the parameter bar when the object is selected
    • If the tool has some new parameters, add the strings for them.

After the steps above, The new tool can be tested by opening simulator/index.html locally in your browser and executing AddingObjType = 'TOOL_ID' with the developer tool to choose the tool, without being on the toolbar.

  1. (optional) Add the corresponding lines in simulator/index.html.

  2. (optional) Add the locale strings for the tool to simulator/locales/en.js:

    • tool_TOOL_ID: the title on the toolbar (or dropdown item)
    • tool_TOOL_ID_popover: the text in the popover when the user hover the item on the toolbar

  3. (optional) Run node sync.js in simulator/locales/ to sync to other locales. Translate the added strings to other locales if you speak that language (follow the translation guidelines).

  4. (optional) Add an exported SVG image (use File -> Export PNG/SVG) of your tools in img/TOOL_ID.svg.

  5. Commit your changes (several times maybe), push to your fork, and create a pull request.

Contributing items to the Gallery

Method 1: By e-mail

  1. Save you work as a .json file using the "Save" button. If your work contains a background image (which can be loaded with "Open"), it should be in a separate file.
  2. Send the files to [email protected]. Include the title of your work, a description of your work (to show on the webpage), and your name to appear on the list of contributors.

Method 2: Via GitHub (preferred if you use GitHub)

  1. Fork this repo and clone locally. If you have forked previously, sync to get the latest changes.

  2. Add the JSON file in gallery/ (follow the naming convention there).

  3. If the work contains a background image, put it also in gallery/, and edit the .json file to include backgroundImage": "IMAGE_FILENAME".

  4. (optional) Take a PNG screenshot with width 1140. It should contain all the tools, texts, and the relavent part of the simulation. Save it in gallery/, with the file name being the JSON file name with .json replaced by .png.

  5. (optional) Take a 250x250 PNG screenshot for the thumbnail. It does not need to contains everything in the simulation, but should contain at least some essential part. Save it in gallery/, with the file name being the JSON file name with .json replaced by -thumbnail.png.

Note: On HiDPI screens, please scale the webpage with the browser first such that the pixel of the canvas matches the pixel of the screens, before taking the screenshots.

  1. (optional) Edit gallery/data.json with a text editor. This file contains the structure of the gallery and the metadata for the items. The ID of an item is the JSON file name without the .json. If you replace an existing items, you can change the title but not the ID, and you should append you name in the list of contributors.

  2. (optional) Run node generate-gallery.js in gallery/.

  3. Commit your changes, push to your fork, and create a pull request.

Contributing translations

You can submit a complete or partial translation for a new language, make progress to an incomplete language, or improve translation for an existing language. You don't need to understand the code to do the translation. Currently, the translation of the Gallery can only be done manually.

  1. Download the target locale file:

    NOTE: If it is indicated above (or in some PR) that some update for a language has been submitted but not yet merged, please wait until it is merged to avoid repeated translation.

  2. Translate the phrase/sentence in the quotation after "message": to the target language. If you encounter < and >, leave the text between them untouched; &amp; means the "&" symbol; \" means a quote, and &nbsp; means an extra space. If the translation of an item is completed, remove the line "incomplete": true,. For example,

  "welcome": {
    "incomplete": true,
    "message": "<span style=\"font-size:22pt\">Welcome to Ray Optics Simulation</span><br>To add an optical component, select a tool and click the blank space.<br>To load an example, please <a href=\"https://phydemo.app/ray-optics/gallery/\">go to the Gallery page</a>."
  },

becomes (for Traditional Chinese)

  "welcome": {
    "message": "<span style=\"font-size:22pt\">歡迎使用「線光學模擬」</span><br>若要加入光學元件，請選擇工具並點擊空白處。<br>若要載入範例，<a href=\"https://phydemo.app/ray-optics/gallery/\">請前往「作品集」頁面</a>。"
  },

After that, you can submit the translated file with either method below:

Method 1: By e-mail

  1. Send the resulting file to [email protected] (you may need to replace the .js with .txt in the filename to make it attachable). Include the name of the language and your name to appear on the list of contributors.

Method 2: Via GitHub (preferred if you use GitHub)

  1. Fork this repo and clone locally. If you have forked previously, sync to get the latest changes.

  2. Save/replace the file as LOCALE_ID.js in simulator/locales/.

  3. (optional) If it is a new language, modify the locale list in simulator/locales/sync.js.

  4. (optional) Add/modify the translation of the welcome message in simulator/index.html.

  5. (optional) Add/modify LOCALE_ID/index.html in the repo root (if not exist, copy from index.html and replace all img/ with ../img/).

  6. (optional) Add the corresponding lines and the <ul class="dropdown-menu" in simulator/index.html

  7. (optional) Add/modify the language-related metadata and the language dropdowns of the homepages in all locales for the new locale.

  8. Commit your changes, push to your fork, and create a pull request.

More contributions

Such as adding a new parameter to a tool, adding a new mode of viewing light, etc. For significant changes such as a new framework or a new toolbar design, please open a new discussion first.

Requirements on compatibility

If you modified some existing tools/components, make sure that the following are satisfied:

  1. If a file is saved before the modification, it should be readable by the app after the modification, with the logic unmodified.
  2. After opening such a file, the appearance within the canvas when none of the objects are selected and the mouse is not over any object should be essentially the same as before the modification (except for quality improvement and bug fixing.)
  3. If the default appearance of a tool (the appearance of an object newly created with the tool, without selection or mouse hovering) is modified, there should be a way to recover the original appearance, such as with a checkbox in the parameter box.

For a feature marked as "beta" and for parameters outside the range of the sliders, 2. and 3. do not apply.