Contributing to Nuxeo

Open Kitchen Philosophy

Founded on the principles of open-source, Nuxeo is passionate about community: the ecosystem of our community users, customers and partners who run their critical content-centric applications on our platform. Open source ensures that these external stakeholders have full visibility into not only the source code but the roadmap and ongoing commitment to standards and platforms. Customers, integrators, contributors and our own developers come together to share ideas, integrations and code, to deliver value to the larger user base.

Nuxeo development is fully transparent:

Our public roadmap can be followed through the Nuxeo Roadmap Documentation Page. Comments are more than welcome!
Any commit in the code can be followed on Nuxeo GitHub repositories and on [email protected].
Any evolution and bug fixing is tracked on JIRA.

Contribution Principles

Nuxeo is always happy when someone offers to help in the improvement of the product, whether it is for documentation, testing, fixing a bug, suggesting functional improvement or contributing new modules. To maintain the quality of such an open development process, Nuxeo has set up a few strict rules that a Nuxeo community member should follow to be able to contribute.

Before describing this process, here are a few points that are the basis of the Nuxeo development process and that should always be kept in mind.

Don’t start coding without warning the Product Manager. This is really important because maybe the code was going to be completely refactored, or the fix was planned and assigned for the next team sprint, or your idea is simply not aligned with our product roadmap and you don’t want to lose your time!
Any change in the Nuxeo sources should match with a JIRA issue (Nuxeo Platform or any other corresponding product: Nuxeo Elements, Browser Developer Extensions, etc.).
Any code change must be documented in English.
Any code change must be unit-tested, this is required to ensure non-regression.
Any code change must be implemented respecting the Coding and Design Guidelines. Typically, the Nuxeo Dev team pays a lot of attention to the code formatting so don’t add useless spaces or newlines if not necessary.
Always create a pull request (PR) on the master branch.

Below are listed the basic step by step instructions to create such a PR. Yet, for complete guidelines about the PR review process, please read the Code Review Guidelines.

Step by Step Instructions

There are two ways to contribute:

By Cloning the GitHub Repository Locally and using command line.
By Using the GitHub UI and make your changes online.

If, for any reason, you don't want to use GitHub, please jump to the Not Using GitHub section.

Cloning the GitHub Repository Locally

We'll take the example of the main Nuxeo repository: the Nuxeo Platform one.

External Contributors

As an external contributor, not member of the Nuxeo GitHub organization, you'll need to work on a fork of the GitHub repository.

Make sure Git is installed and configured.
Clone the GitHub repository:
```
 git clone [email protected]:nuxeo/nuxeo.git
```
This does a checkout of the default master branch.

If you've already cloned the repository in the past, make sure that:
- You are in the directory of the cloned repository.
- You are on the master branch, if not checkout this branch.
- The branch is up-to-date:
```
  git pull
```
Create a new branch, respecting the Nuxeo branch naming policy <TYPE>-<JIRA_ISSUE>-<SHORT_DESCRIPTION>.
- As a TYPE, choose between fix, feature, improvement or task.
- JIRA_ISSUE is the reference of the related Jira issue.
- SHORT_DESCRIPTION should state what the changes in this branch do, using lowercase with hyphens.
For instance:
```
git checkout -b 'fix-NXP-29237-make-drive-work-with-mongodb-audit'
```
Open your favorite IDE and apply your changes.
Add your changes to the Git index:
```
 git add -A
```
Add a commit message, respecting the Nuxeo commit conventions <JIRA_ISSUE>: <MESSAGE>.
- JIRA_ISSUE is the reference of the related Jira issue. Most of the time, it is the same than the one in the branch name. Yet, it is OK to have additional commits referencing other JIRA issues within the same branch/PR.
- MESSAGE should state what the change in this commit does.
For instance:
```
git commit -m 'NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB'
```
You can also add a description along with the commit message by not specifying anything in the command line.
```
git commit
```
This prompts for a multiline string in which the first line is the commit message, any line below the description.
```
NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB

By adding the missing Nuxeo Drive change finder implementation for MongoDB.
```

Push your changes to the newly created branch in GitHub:

 git push -u origin fix-NXP-29237-make-drive-work-with-mongodb-audit

Go to the GitHub UI and click on the button to create a PR.

By default, the name of the PR is either the commit message in the case of a single commit or the branch name with spaces instead of hyphens. You can leave it as is or set a custom name, maybe more explanatory.

Don’t hesitate to:
- Add a first comment to explain your contribution.
- Request explicitly some reviewers if you are aware of people in charge of the piece of code touched by the PR, or you simply think of someone legitimate or who could be interested.
Your contribution is then going to be reviewed by the Dev team, or more specifically the requested reviewers.

To get a complete view of the review process and what is expected by the reviewers, please read the Code Review Guidelines.
Once the reviewers have added some comments, you must:
- Take into account all comments requesting changes, either by doing the requested changes (then it's a good idea to 👍 the comment), or by discussing further and getting to a consensus between you and the commenters.
- Reply to any other comment, or simply acknowledge with an appropriate emoji reaction.
- If there are fixes to do, amend the commits (see below), don't create further commits for the fixes (think about people reading commits one by one to understand the logic of the code).
- After you've done fixes and amended code, add a comment in the PR to summarize your changes, and ask the commenters and reviewers for another review.
To amend a commit, there are several solutions, among which the following two.
1. If you have a single commit in the PR or the change to apply impacts the latest commit, you can simply amend it:
```
 git add -A
 git --amend
```
  You can also amend the commit message and description if needed.
2. If you have several commits in the PR and the change to apply impacts an older commit than the latest one, you can use interactive rebase.
  
  Let's say you have the following commits, from latest to oldest:
```
 NXP-29237: an improvement related to this fix
 NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB
 NXP-29237: format
```
  If you want to amend NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB:
```
 git add -A
 git commit -m 'take into account requested changes' # here we don't care about the commit message
```
  The commit list then looks like:
```
 take into account requested changes                           # HEAD
 NXP-29237: an improvement related to this fix                 # HEAD~1
 NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB # HEAD~2
 NXP-29237: format                                             # HEAD~3
```
  Run the interactive rebase:
```
 git rebase HEAD~3 # points the parent commit of the commit to amend
```
  This prompts for a multiline string listing the commits to rebase, in the reverse order compared to git log, meaning from oldest to latest:
```
 pick 2d2a4755dec NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB
 pick 0b63f36c3d4 NXP-29237: an improvement related to this fix
 pick ecc74f6996e take into account requested changes
```
  Reorder the commits to put the commit including the new changes just below the commit to amend:
```
 pick 2d2a4755dec NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB
 pick ecc74f6996e take into account requested changes
 pick 0b63f36c3d4 NXP-29237: an improvement related to this fix
```
  Mark the commit including the new changes as fixup:
```
 pick 2d2a4755dec NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB
 fixup ecc74f6996e take into account requested changes
 pick 0b63f36c3d4 NXP-29237: an improvement related to this fix
```
  Save and exit, the commit list will then look like:
```
 NXP-29237: an improvement related to this fix
 NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB
 NXP-29237: format
```
  In the end, it's the same list as originally in the PR, but you can note that the SHA1 has changed for the commit NXP-29237: allow using Nuxeo Drive with audit logs in MongoDB , since it was amended to include the new changes.
Once the commits were amended and you think the PR is ready for a new review, push the amended branch to GitHub using the --force option since you're actually rewriting its history. Note that this is OK, and permitted, since it is a work branch, not the master branch.
```
git push -f origin fix-NXP-29237-make-drive-work-with-mongodb-audit
```
Finally, don't hesitate to re-request a review from the reviewers in GitHub.
Once your PR is valid in GitHub, click on the Rebase and Merge button. Valid here means that:
- The changes have been approved by the reviewers.
- All checks have passed.
- The branch has no conflicts with the base branch when rebasing.
The following example shows a valid PR in GitHub that can be rebased and merged:

Using the GitHub UI

If you need to edit a single file, you can use the default GitHub UI feature to create a PR.

Click on the edit icon:
Make your changes.
Add a commit message, respecting the Nuxeo commit conventions <JIRA_ISSUE>: <MESSAGE>, add an optional description and set the branch name, respecting the Nuxeo branch naming policy <TYPE>-<JIRA_ISSUE>-<SHORT_DESCRIPTION>:

Not Using GitHub

You can still contribute patches without using GitHub:

Create a JIRA issue describing the problem and what you plan to do (or what you did, if it comes afterwards).
Fork the GitHub repository you want to patch and work on the master branch.
Make your changes, respecting the Coding and Design Guidelines, and check that they don't break existing unit tests.
Create a patch file and attach it to the JIRA issue you've created.
The patch will either be validated or you will receive feedback with guidance to complete it.
The patch will be committed by a Nuxeo developer.

Product Specificities

Nuxeo Web UI / Nuxeo Elements

Ensure to execute npm run lint and npm run format to try to fix the format issues automatically before creating your commit. Be aware we have a command that helps us to have the code properly formatted.

Translations

Nuxeo labels are stored in ASCII files. We use the UTF-8 encoding for non ASCII files (like \u00e9 for é). You have two different options.

See HOWTO: Translate the Nuxeo Platform for more details.

With Crowdin (non-English Translations)

Join the Nuxeo translation group of your choice at crowdin.net/profile/nuxeo. Pick a language you want to translate and start by clicking Translate.
In the Crowdin translation view you will find all the phrases to translate to the left. (To view only the ones that still need translation, use the Untranslated filter.)
Click on a phrase you want to translate. You see the original phrase in the top, and a box to fill out your translation beneath.
Enter the translation and by clicking Save, and optionally, if you're a proofreader, you can approve the translation.
Contact one or several of the Crowdin project managers to be credited for your contribution.

Without Crowdin (English Translations)

For now, English translations are managed only on GitHub.
- For Web UI labels, edit the Nuxeo Web UI or Nuxeo UI Elements JSON files.
- For JSF UI labels, looking at the reference messages.properties file can help you understand in which GitHub repository or module the original translation is. For instance, look for the following sample lines:
```
## DO NOT EDIT FOLLOWING LINE
# Translations from ./nuxeo/nuxeo-features/nuxeo-platform-lang/src/main/resources/web/nuxeo.war/WEB-INF/classes/messages_en_US.properties

[...]

## DO NOT EDIT FOLLOWING LINE
# Translations from ./nuxeo/addons/nuxeo-agenda/src/main/resources/OSGI-INF/l10n/messages_en_US.properties

[...]
```
  If the module is under the addons directory, it will be in a specific GitHub repository. Otherwise, it will be in the main Nuxeo repository.
Use any standard Java i18n tool to edit the files.
Make a pull-request on GitHub.

Documentation

Contribution is welcome both for technical (books and guides, FAQ, tutorials) and functional documentation. Don't hesitate to contribute directly to the GitHub repository.

Testing

Testing is always welcome, particularly when Nuxeo releases a new version of its products. As our products are easily downloadable, it doesn't require any specific development skill.

Download the version you want to test, set it up.
Get and read the user guide for the selected distribution and add-ons.
For any bug you detect, ask for a confirmation on Nuxeo Answers, create a JIRA issue, specifying the version of the product, the environment (OS, browser, ...), the conditions and the reproduction steps. Before each release, every JIRA issue is read and depending on its severity, fixed before the release or postponed.

New Modules

Nuxeo is highly modularized and as a consequence, it is totally possible to develop a new feature that will be deeply mixed with the existing interface. If you have such a project, Nuxeo will be glad to help you designing your module, and to provide a GitHub repository, aside from a web page (Wiki) and a JIRA project for the visibility of your development.

Start by an introductory email to the partners mailing list, explaining the purpose of the new module you want to develop (BEFORE developing it) and how you think of doing it or how you did it (although it is always better to contact the list before).
After a few exchanges in the mailing list, return the Contributor Agreement signed. Nuxeo will then add you to the GitHub organization and give you rights to commit in a new GitHub repository.
Read and respect the Coding and Design Guidelines.
Commit your development regularly (meaning don't wait to finish everything: on the contrary commit each of your developments on a very atomic mode, mentioning the purpose of your commit in JIRA (take it as an advice more than a rule).
Unit tests are mandatory and Test Driven Development is strongly encouraged. Functional tests could also be integrated. We'll put your module under continuous integration, if the quality of the code respects Nuxeo criteria.
Package your plugin as a Nuxeo Package, if you want it to be on Nuxeo Marketplace. Plus it will be much easier for people to install it.

In addition to code conventions and development good practices above-mentioned, when creating a new module you should also consider the following recommendations:

Align your code on a recently released version or on the latest development version.
Provide a clean POM (well indented, no duplication, inheriting the nuxeo-ecm POM, ...).
If needed, provide a list of the artifacts (libraries) or Public Maven repositories that should be added to the Nuxeo Maven repository to be able to build.
Avoid embedded libraries.
Avoid introducing new libraries if the equivalent already exists in Nuxeo.

Contributor Agreement

Click here to download the Nuxeo Contributor Agreement (PDF).

For small patches and minimal changes, one doesn't need a contributor agreement, as it cannot be considered original work with a separate license and copyright. The contributor agreement is for folks who contribute non-trivial amounts of code (at least one new file for instance).

The signature of the Contributor Agreement is mandatory for a GitHub pull request to be accepted. You will be prompted for the signature in the PR comments or you can browse the CLA assistant