Contributing.md

   1 # Contributing to WeeChat scripts
   2
   3 ## Reporting an issue
   4
   5 Issue must be reported to upstream repository, not this one (most of times, the upstream repository is mentioned in the script itself).\
   6 If you don't know where is the upstream repository, please contact directly the author by e-mail.\
   7 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.
   8
   9 ## Testing pending scripts
  10
  11 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.
  12
  13 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`).\
  14 Whether the script is working or not, please comment the pull request accordingly.
  15
  16 Thank you for your help!
  17
  18 ## Adding a new script
  19
  20 New scripts are added with pull requests against master branch of this repository, using the pull request template called `Add script`.
  21
  22 **Important:** please fill the pull request template and follow **all** these rules, otherwise your new script will be rejected:
  23
  24 - pull request:
  25   - fill the pull request template
  26   - 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
  27   - use this commit message: `New script name.py: short description…`
  28 - script feature:
  29   - check that no script or [pending script](https://github.com/weechat/scripts/pulls) does exactly same thing as your script
  30 - script name:
  31   - use max 32 chars, only lower case letters, digits and underscores
  32   - use a unique name, not used by any other script, even in a different language
  33   - use the script name (without extension) in the call to the `register` function
  34   - 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)
  35 - script content:
  36   - do **NOT** use a shebang on the first line (like `#!/usr/bin/perl`), this is not needed
  37   - write a comment at the beginning with your name (or pseudo), your e-mail and the chosen license (which must be free)
  38   - consider using [Semantic versioning ](https://semver.org/) (recommended, not mandatory); only digits and dots are allowed in version
  39   - use only English for code and comments
  40   - do **NOT** use an extra API between WeeChat and your script (like Ruby gem "WeeChat"), use the standard WeeChat API only
  41   - use function [hook_process](https://weechat.org/files/doc/stable/weechat_plugin_api.en.html#_hook_process) or [hook_process_hashtable](https://weechat.org/files/doc/stable/weechat_plugin_api.en.html#_hook_process_hashtable) if your script is doing something blocking (like fetching URL), to not block WeeChat
  42   - make your Python script compatible with Python 3.x, the support of Python 2.x is now optional
  43   - use the official WeeChat URL: [https://weechat.org](https://weechat.org) (`https` and no `www.`) in any link to the WeeChat website.
  44
  45 Your script is automatically checked in CI, see [Automatic checks on scripts](#automatic-checks-on-scripts).
  46
  47 ## Updating a script
  48
  49 ### Contacting the author
  50
  51 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.
  52
  53 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.\
  54 Then the author will send a pull request on this repository.
  55
  56 ### Reporting a vulnerability
  57
  58 Please **DO NOT** file a GitHub issue for security related problems, but send an email to [security@weechat.org](mailto:security@weechat.org) instead.
  59
  60 ### Sending the new release
  61
  62 Scripts updates are made with pull requests against master branch of this repository, using the pull request template called `Fix script` or `Improve script`.
  63
  64 **Important:** please fill the pull request template and follow **all** these rules, otherwise your script update will be rejected:
  65
  66 - pull request:
  67   - fill the pull request template
  68   - 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
  69   - use this commit message: `name.py 1.3: fix some bug…` (`1.3` being the new version of script `name.py`)
  70 - script content:
  71   - update the version number in the script (used in `register` function) and the ChangeLog, if there is one
  72   - 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
  73   - make any Python script compatible with Python 3.x, the support of Python 2.x is now optional.
  74
  75 The script is automatically checked in CI, see [Automatic checks on scripts](#automatic-checks-on-scripts).
  76
  77 ## Deleting a script
  78
  79 Deleting a script must be done for a justified decision, for example such reasons are valid:
  80
  81 - the feature implemented by the script has been implemented in WeeChat itself, so the script is no longer of interest
  82 - the web service used by the script has been discontinued, so the script can not work at all any more
  83 - the script uses dependencies that are not maintained any more or subject to vulnerabilities not fixed, thus impacting WeeChat itself.
  84
  85 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.
  86
  87 **Important:** please fill the pull request template and follow **all** these rules, otherwise your script deletion will be rejected:
  88
  89 - pull request:
  90   - fill the pull request template
  91   - make only one commit to delete only one script
  92   - use this commit message: `Remove script name.py`, and it is recommended to explain the reasons in the commit description
  93
  94 ## Automatic checks on scripts
  95
  96 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.
  97
  98 You must run this script prior to submit the pull request, and the score displayed must be 100 / 100.
  99 If errors or warnings are detected in the script, you must fix them before the script is manually tested/merged by the WeeChat team.
 100
 101 See the [weechat-script-lint repository](https://github.com/weechat/weechat-script-lint) for more information about the checks performed and how to use the script.