Skip to content

Latest commit

 

History

History
101 lines (69 loc) · 6.56 KB

Contributing.md

File metadata and controls

101 lines (69 loc) · 6.56 KB
Raw

Contributing to WeeChat scripts

Reporting an issue

Issue must be reported to upstream repository, not this one (most of times, the upstream repository is mentioned in the script itself).
If you don't know where is the upstream repository, please contact directly the author by e-mail.
If you have no answer, or if the author has no time to fix the problem, then you can report the issue in the tracker or send an update of the script if you are able to fix yourself.

Testing pending scripts

Your can help WeeChat team by testing the pending scripts (new scripts or updates): this makes script approbation faster and this ensures there are no major bugs in the script itself.

To do that, you can download the script in the pull request and load it manually in WeeChat (for example: /script load /path/to/new_script.py).
Whether the script is working or not, please comment the pull request accordingly.

Thank you for your help!

Adding a new script

New scripts are added with pull requests against master branch of this repository, using the pull request template called Add script.

Important: please fill the pull request template and follow all these rules, otherwise your new script will be rejected:

  • pull request:
    • fill the pull request template
    • make only one commit with one new file (the new script) in the appropriate directory, for example python/ if you add a new Python script
    • use this commit message: New script name.py: short description…
  • script feature:
    • check that no script or pending script does exactly same thing as your script
  • script name:
    • use max 32 chars, only lower case letters, digits and underscores
    • use a unique name, not used by any other script, even in a different language
    • use the script name (without extension) in the call to the register function
    • do NOT use the word "weechat" in the script name: for example prefer notify.py to weechat_notify.py (the script is only for WeeChat)
  • script content:
    • do NOT use a shebang on the first line (like #!/usr/bin/perl), this is not needed
    • write a comment at the beginning with your name (or pseudo), your e-mail and the chosen license (which must be free)
    • consider using Semantic versioning (recommended, not mandatory); only digits and dots are allowed in version
    • use only English for code and comments
    • do NOT use an extra API between WeeChat and your script (like Ruby gem "WeeChat"), use the standard WeeChat API only
    • use function hook_process or hook_process_hashtable if your script is doing something blocking (like fetching URL), to not block WeeChat
    • make your Python script compatible with Python 3.x, the support of Python 2.x is now optional
    • use the official WeeChat URL: https://weechat.org (https and no www.) in any link to the WeeChat website.

Your script is automatically checked in CI, see Automatic checks on scripts.

Updating a script

Contacting the author

Before updating a script, if you are not the author of the script, you must contact the author of script directly, and discuss about your changes to check if it's OK, especially if you are adding new features or if you are changing the behavior of the script.

For example, if the author uses a GitHub repository for the script, you can send a pull request to the author instead of sending directly to this repository.
Then the author will send a pull request on this repository.

Reporting a vulnerability

Please DO NOT file a GitHub issue for security related problems, but send an email to security@weechat.org instead.

Sending the new release

Scripts updates are made with pull requests against master branch of this repository, using the pull request template called Fix script or Improve script.

Important: please fill the pull request template and follow all these rules, otherwise your script update will be rejected:

  • pull request:
    • fill the pull request template
    • make only one commit on one file in the pull request (the script actually updated); exceptions are allowed if motivated in the pull request description
    • use this commit message: name.py 1.3: fix some bug… (1.3 being the new version of script name.py)
  • script content:
    • update the version number in the script (used in register function) and the ChangeLog, if there is one
    • do NOT update the author name in script (used in register function), it must always contain the original script author, even if you are doing large updates in the script
    • make any Python script compatible with Python 3.x, the support of Python 2.x is now optional.

The script is automatically checked in CI, see Automatic checks on scripts.

Deleting a script

Deleting a script must be done for a justified decision, for example such reasons are valid:

  • the feature implemented by the script has been implemented in WeeChat itself, so the script is no longer of interest
  • the web service used by the script has been discontinued, so the script can not work at all any more
  • the script uses dependencies that are not maintained any more or subject to vulnerabilities not fixed, thus impacting WeeChat itself.

If you are not the author of the script, you must first contact the author to discuss about the deletion: the author could have a different opinion or could make changes to keep the script.

Important: please fill the pull request template and follow all these rules, otherwise your script deletion will be rejected:

  • pull request:
    • fill the pull request template
    • make only one commit to delete only one script
    • use this commit message: Remove script name.py, and it is recommended to explain the reasons in the commit description

Automatic checks on scripts

Whenever a script is added or updated, the script weechat-script-lint is executed by CI in GitHub Actions and looks for errors in the script.

You must run this script prior to submit the pull request, and the score displayed must be 100 / 100. If errors or warnings are detected in the script, you must fix them before the script is manually tested/merged by the WeeChat team.

See the weechat-script-lint repository for more information about the checks performed and how to use the script.