Contributing to SPIP development

Register on git.spip.net

To submit a change on git.spip.net you need to :

1. read the SPIP welcome charter, then, if you agree with it ;
2. register on the discussion forum;
3. request write rights using the dedicated form on contrib.spip.net.

Contributing rules

1. Create a ticket on https://git.spip.net/spip/spip/issues before sending a proposal (which is called a PR [1]).
2. Create a personal copy of the repository (a fork) and create a branch that will contain the proposed changes. This branch should be named issue_xxx, where xxx is the related ticket number.
3. Messages from issue_xxx branch commits must follow the Conventional Commits nomenclature. The body of the message should be clear and explanatory : it should describe the problem being addressed and the changes or corrections being made. In addition, care should be taken to add a line in the CHANGELOG file of the repository on the same branch but in a separate commit to avoid conflicts during the merge. Finally, the series of commits must be linear (without merge commits).
4. Once the branch is finalized, make a merge request via the Gitea interface by clicking on "new merge request" from the branch in question. Make sure the PR doesn’t contain any conflicts. In case there is are some conflicts, correct them using git rebase and git force push. The request will be reviewed and tested. It can only be merged after receiving at least two approvals from spip-team members.
5. The issue_xx branch can be deleted after the merge.

The same rules apply to team members, for whom it is recommended that they always create a PR before putting code into the master branch. However, if the patch is really minor and the person is sure it won’t break anything, he or she may decide to send it directly to the master branch as long as he or she follows up. These members can create the branch directly in the repository, without forking.

he or she may decide to send it directly to the master branch as long as he or she follows up.

About Conventional Commits and CHANGELOG Files

The list of available types for conventional commits is as follows: build, change, chore, ci, deprecate, doc, feat, fix, perf, remove, revert, security, style, test, i18n (details on git.spip.net). The type may be supplemented by a scope in parentheses to specify the component or feature being modified (examples with commits 13a90d3878 et 5512ce374b).

The footer of the message must contain a reference to the ticket linked to the PR in the form of Refs: #XXX or Fix: #XXX to close the ticket automatically on merge.

Example of a fully completed commit log:

fix: réparer le lien vers la licence GPL dans le pied des pages du privé

en le remplaçant par un simple lien vers le site officiel gnu.org

Fix: #5328

CHANGELOG files follow the standard Keep a changelog. Each changelog entry must:

• reference the ticket (or the PR if there is no corresponding ticket)
• clearly and concisely describe the changes made by the PR (you can simply use the first line of the commit message for this)

Example of a changelog entry corresponding to the previous commit log:

- #5328 Réparer le lien vers la licence GPL dans le pied des pages du privé

Rules of presentation and writing

See Coding rules.

Programming rules

Think

Before programming any new functionality, think first about...

-  the methods and algorithms used for its implementation:
lightness, performance, stability (don’t overlook making some rough calculations to validate your choices);
-  suitability to the project: portability, security, flexibility;
-  implications on other functionalities: modifications and additions that will need to be made to other existing functionalities;
-  the "natural" place for this functionality within the entire project:
in terms of interface, file locations, etc.

Do not overlook any refactoring or realigning of code that will be required
(by functions, especially considering files that must be included).
On the other hand, avoid wherever possible the inclusion of files containing non-function code (except where such inclusions are "natural" and deliberately intended).

Naming

Generally speaking, names should be neither too short nor too long: just sufficiently explanatory. This rule is particularly important for global variables which can be shared between several files and/or several functions. For local variables (i.e. used in only one function), the rule is more flexible. In particular, it is permitted to use variables of only a single letter in order to make complex expressions more compact. Note that in almost all programming languages, there are a certain number of particular letters which are traditionally employed for "standardised" usage (examples: $i, $j for loop counters, $n for numbering, $t for time or duration in seconds, etc.). Not contravening such standard industry practice will allow any future readers to more quickly understand what’s going on.

Testing

Once a significant modification has been made, it’s a good idea to test it yourself thoroughly, without just waiting for someone else to do it for you. For SPIP, this entrails verifying that the programme works correctly on a certain number of web hosts and with a variety of possible configurations (e.g. different versions of PHP or MySQL, greater or lesser restrictions imposed on directory access rights...) ; but also in a certain number of different situations, including those most commonly encountered in practice (especially as regards any graphical interfaces constructed) - different browsers, different operating systems, etc.