Contributing

Any help is welcome!

If you encounter a problem using one of Notoy’s browser extensions, a task it not as easy as you’d like it to be or you’d like something added to it: open an issue at GitHub, see section Report Issues.

Report Issues (Bugs and Feature Requests)

Please help making Notoy better by filing bug reports and feature requests.

File a bug report at GitHub bur report).
Add a feature request at GitHub feature request.
Take a look at the Issue Tracker at GitHub

Forking the Repository

If you’d like to contribute directly, e.g. better the documentation, add another language or write some source code: fork Notoy by clicking the Fork button in the upper right corner of the GitHub project website. Check out your fork of Notoy using the URL from the Code button of your fork on Github. The URL should be something like github.com/YOUR_USERNAME/Notoy.git.

Details about how to fork a repository on Github are here.

Make your changes, push them to your forked repository and make a pull-request (e.g. using the Pull request-button above and right of GitHubs source file view).

See GitHub on Pull-Requests and another How-To.

Github Documentation on Collaborating with Issues and Pull Requests

See GitHub’s documentation about how to contribute for details: Collaborating with issues and pull requests.

Developing Notoy

Changing and Generating Documentation

Installing Dependencies

To generate the documentation using MkDocs, a virtual Python environment is needed. First you need to install Python, if you don’t have it installed already - either from your distributions repository, using the XCode or Homebrew version, or getting it from Python.org.

See

In the file Pipfile there is a stanza saying

[requires]
python_version = "3.9"

That’s just because I used 3.9 when generating that documentation, and Pipenv is picky about the version mentioned there. Just edit that to match your installed Python version.

Install pipenv using the package manager pip

pip install pipenv

Now you’re ready to download and install the needed packages using pipenv

pipenv install --dev

After that you can use MkDocs.

Call

pipenv run mkdocs serve

in the root directory of Notoy and connect to the running webserver at http://127.0.0.1:8000.
This preview shows changes in realtime, so any changes to the markdown files in docs you see as preview as soon as you save the file. The generated HTML files are saved in the directory sites.

MkDocs Files

  • mkdocs.yml - the MkDocs configuration, specially the configuration of the navigation sidebar in nav which you may need to edit
  nav:
  - Home: index.md
  - Project Links:
      - "Downloads": https://github.com/Release-Candidate/Notoy-BrowserExtensions/releases/latest
      - "GitHub Project Page": "https://github.com/Release-Candidate/Notoy-BrowserExtensions"
      - "Report a Bug or a Feature Request": "https://github.com/Release-Candidate/Notoy-BrowserExtensions/issues/new/choose"
      - "Issue Tracker at GitHub": "https://github.com/Release-Candidate/Notoy-BrowserExtensions/issues"
  - "Installation & Usage":
      - "Installation & Usage": usage.md
      - "License": license.md
  - Contributing:
      - Contributing: contributing.md
  • docs/ - the markdown files that are used to generate the
    HTML sites in the directory sites/

Read the Docs Configuration

  • .readthedocs.yaml the configuration for Read the Docs
  • docs/requirements.txt the packages needed by MkDocs
    when generating the documentation at Read the Docs.
    Locally needed packages are configured in Pipfile

Read the Docs automatically generates the MkDocs documentation after each git push.

GitHub Documentation

The Markdown documentation for GitHub are the files README.md and CHANGELOG.md in the project root directory.

Source Code

Before you can use the configured Tools of this project, you have to download and install the needed tools.

NPM and Gulp

Notoy uses NPM and Gulp to build the packages.

To install NPM, download and install Node.js for your OS: Node.js Website

To install all needed tools, run (npm install --dev should not be needed, npm install should do the same).

npm install
npm install --dev

Now you can use the following NPM scripts:

  • npm run lint - To run ESLint on all Javascript files in the project
  • npm run list - To see the list of all Gulp tasks
  • npm run pack - To copy the images and translations to the browser folders and pack them with the sources.
  • npm run clean - To delete all copied directories and zip files generated by npm run pack

Pipenv and MkDocs

To generate the documentation using MkDocs (see Changing and Generating Documentation), a virtual Python environment is needed. So, first you need to install Python, if you don’t have it installed already - either from your distributions repository, using the XCode or Homebrew version, or getting it from Python.org.

In the file Pipfile there is a stanza saying

[requires]
python_version = "3.9"

That’s just because I used 3.9 when generating that
documentation, and Pipenv is picky about the version mentioned
there. Just edit that to match your installed
Python version.
Install pipenv using the package
manager pip

pip install pipenv

Now you’re ready to download and install the needed packages using pipenv

pipenv install --dev

After that you should be able to use the executable mkdocs in the local virtual Python environment in your project root using pipenv run:

pipenv run mkdocs --version

GitHub Workflows

All tests and builds are executed on Linux.

These are the GitHub workflows defined in the directory .github/workflows

GitHub Issue Templates

Issue templates for GitHub in .github/ISSUE_TEMPLATE/

  • bug_report.md Bug report template
  • feature_request.md Feature request template

What is What? - List of all Files

A list of all files in this repository and what they do or configure.

  • ./README.md - The main documentation file.
  • ./LICENSE - The project’S license, GPLv3.
  • ./CHANGELOG.md - The project’s changelog.
  • ./.prettierrc.json - Configuration file for Prettier, a source code formatter.
  • ./package.json, package-lock.json - List of NPM packages (and Gulp plugins) needed by Notoy
  • ./gulpfile.js - Gulp configuration script
  • /.eslintrc.json - ESLint configuration
  • ./notoy-browser_extensions.code-workspace - The Visual Studio Code workspace file.
  • ./.vscode/ - Directory containing additional Visual Studio Code configuration.

GitHub Workflows & Issue Templates

Directory ./github/ISSUE_TEMPLATE/:

  • ./.github/ISSUE_TEMPLATE/bug_report.md - Bug report template for GitHub
  • ./.github/ISSUE_TEMPLATE/feature_request.md - Feature request template for GitHub

Directory ./.github/workflows/:

MkDocs documentation

  • ./Pipfile - Packages nedded by MkDocs to install using pipenv and the package mkdocs itself.
  • ./mkdocs.yml - The configuration file for MkDocs, contains the website’s index:
nav:
  - Home: index.md
  - Project Links:
      - "Downloads": https://github.com/Release-Candidate/Notoy-BrowserExtensions/releases/latest
      - "GitHub Project Page": "https://github.com/Release-Candidate/Notoy-BrowserExtensions"
      - "Report a Bug or a Feature Request": "https://github.com/Release-Candidate/Notoy-BrowserExtensions/issues/new/choose"
      - "Issue Tracker at GitHub": "https://github.com/Release-Candidate/Notoy-BrowserExtensions/issues"
  - "Installation & Usage":
      - "Installation & Usage": usage.md
      - "License": license.md
  - Contributing:
      - Contributing: contributing.md
  • https://readthedocs.org/, to host the generated documentation.

Directory ./docs:

  • docs/requirements.txt - Packages (plugins for MkDocs) that have to be installed by Read the Docs to generate the documentation.
  • ./docs/index.md - The documentation’s home page.
  • ./docs/usage.md - Usage information.
  • ./docs/contributing.md - Information on how to contribute to the project.
  • ./docs/license.md - The license of the Notoy browser extensions, GPLv3

Directory ./run_haddock.bat. Sadly I haven’t found a way to generate that documentation using mkdocs build, which is what Read the Docs calls to build it. So for now it is included in the source repository (but not the Stack template file).

Translations

Each language has its own file containing the translated texts in a subdirectory of the directory _locales/ named after the language.

Examples:

  • German translation: ./_locales/de/messages.json
  • English translation: ./_locales/en/messages.json

A translation file in JSON format looks like this:

{
  "extensionName": {
    "message": "Notoy",
    "description": "Name of the extension."
  },
  "extensionDescription": {
    "message": "Saves a link to the current active tab with its title, keywords and a long and short description as markdown, Org-Mode or plain text",
    "description": "Description of the extension."
  },
  "browserExtension": {
    "message": "browser extension",
    "description": "Translation of 'browser extension'"
  },
  "previewDescription": {
    "message": "This is a short description of the content of the website, usually set by the website itself, but you can change that.",
    "description": "Short description for the preview in the 'options' page"
  },
  ...
}

Javascript sources, HTML and CSS

  • manifest.json - The extension’s configuration, one for each supported browser
  • formatContent.js - Functions and constants needed by the other source files
  • background.js - The source of the background script, that saves the title, url, short description and keywords of the current tab
  • options.js - The option page of the extension, Javascript source
  • options.html - The option page of the extension, HTML
  • options.css - The option page of the extension, CSS
  • popup.js - The popup of the extension, Javascript source - main source file
  • popup.html - The popup of the extension, HTML
  • popup.css - The popup of the extension, CSS