Developer Documentation

Contributing to Nuxeo

Updated: June 12, 2020

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:

Contribution Principals

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 edit directly the code 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 evolution in Nuxeo sources should match with a JIRA issue (Nuxeo Platform or corresponding product Browser Developer Extensions, Nuxeo Elements, Nuxeo Studio...).

  • Any code evolution must be documented in English.
  • Any new feature, even a low-level one, must be unit-tested.
  • Any new feature must be implemented respecting usual Nuxeo software design, leveraging services, not putting business logic in Seam components. A bad designed code could be rejected.
  • Any PR should have only one commit message in general, so commit when you’re sure you’re done. That said, we may need to split the code into different commits for several reasons (organization, code that may go to master but not into maintenance branches).
  • The Nuxeo Dev team pays a lot of attention to the code formatting so don’t add useless spaces or newlines if not necessary (some IDE, like Atom, for example, creates a useless empty line at the end of the file, so adjust your settings).

Step by Step Instructions

There are two ways to contribute:

Cloning the Repository Locally

  1. Clone the GitHub repository:

    git clone https://github.com/nuxeo/nuxeo.git
    
  2. Ensure the branch you’re working on is up to date:

    git pull
    
  3. Create a branch, respecting the conventions:

    • If you’re not working on master branch, prefix it with the branch name
    • As a prefix, choose between fix, feature or improvement
    • Add the NXP ticket number
    • Add a short description, starting by a verb, all lowercase with hyphens
    git checkout -b '10.10-HF/fix-NXP-28805-review-retention-automation-operations'
    git checkout -b 'feature-NXP-28804-add-quickfilter-docs-with-retention-rules'
    
  4. Open your favorite IDE and apply your changes.

  5. Add your changes on git:

    git add -A
    
  6. Add a commit message, respecting the naming conventions <TICKET_NUMBER>: <description lowercase>:

    git commit -m 'NXP-28804: add quick filter for docs in retention'
    
  7. Push your changes:

    git push origin 10.10-HF/fix-NXP-28805-review-retention-automation-operations
    git push origin feature-NXP-28804-add-quickfilter-docs-with-retention-rules
    
  8. Go to the GitHub UI and click on the button to create a PR. Don’t hesitate to add a small comment to explain your contribution:

    pr.png
    pr.png
    Pull Request Review
    Your contribution is going to be reviewed by the Dev team or the component leader. They will probably ask you to update some code sections. So take the review, answer them, and edit your code accordingly.

  9. (Optional) At this stage, you might have 2 commit messages. The first one from your original PR, another one with some updates.

    • To merge and rewrite your commit, run git rebase -i HEAD~2
    • The terminal will open the interactive rebase. You should end up with two lines, corresponding to those two commits.
    • Prefix the first commit message with pick
    • Prefix the second commit message with fixup
    • Push force the modification: git push --force
    • And repeat it until there is nothing left to review!
  10. Once your contribution is approved, go to your PR on GitHub, click on Rebase and Merge button.

    rebase-and-merge.png
    rebase-and-merge.png

Using GitHub UI

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

  1. Click on the edit icon:

    github-ui-edit.png
    github-ui-edit.png

  2. Make your changes and add a commit message, and update the branch name respecting the naming conventions:

    github-ui-commit.png
    github-ui-commit.png

Product Specificities

Nuxeo Platform

Don’t forget to Test and Push (T&P) after getting the number of required approvals (manual operation needed for now).

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 &eacute;). You have two different options.

See HOWTO: Translate the Nuxeo Platform for more details.

With Crowdin (non English translations)

  1. 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.
  2. 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.)
  3. 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.
  4. Enter the translation and by clicking Save, and optionally, if you're a proofreader, you can approve the translation.
  5. Contact one or several of the Crowdin project managers to be credited for your contribution.

Without Crowdin (English translations)

  1. For now, English translations are managed only on GitHub.

    ## 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.

  2. Use any standard Java i18n tool to edit the files.

  3. 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 submits a new Fast Track version of its products. As our products are easily downloadable, it doesn't require any specific development skill.

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

Improvements and Bug Fixes

Improving a module is always welcome and is carefully managed by Nuxeo developers. The process is to go through a JIRA "Contribution" ticket and GitHub. Depending on the nature of your changes, you might be asked to sign and return the Contributor Agreement. This is mandatory for everything that isn't minor improvement or bugfix. You may get credentials to commit directly when you get used to submitting pull requests and that those one respect the framework logic and quality rules.

  1. Create a JIRA "Contribution" ticket that will hold a description of your improvements, functionally and technically.
  2. Nuxeo will approve your specifications (or ask you some more information/change) and will give you recommendations. The JIRA issue will be in "specApproved" state.
  3. Read the Coding and design guidelines.
  4. Fork the project on GitHub.
  5. Do your modifications in a new branch named FEATURE-the_Jira_issue-a_short_description, respecting the coding and design guidelines. Be sure it doesn't break existing unit tests.
  6. Send a pull-request.
  7. In JIRA, set the ticket to "devReview" state and give a link to your pull request.
  8. Finally, we can ask for some changes, putting comments on your code, then your branch will be merged by a Nuxeo developer.

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. Our main recommendation, among respecting coding rules and design, is to respect the usual code layout: core, API, facade, web, … 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.

  1. 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).
  2. 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.
  3. Read and respect the Coding and design guidelines.
  4. 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).
  5. 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.
  6. 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 take the following recommendations into considerations:

  • Align your code on a recent released version or on the latest development version.
  • Provide a clean POM (well indented, no duplication, inheriting 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.

Not using GitHub?

You can still contribute patches even without using GitHub:

  1. Create a JIRA ticket of type "Contribution" describing the problem and what you plan to do (or what you did, if it comes after).
  2. Read the Coding and design guidelines.
  3. Fork the "master" branch of the sub-project you want to patch.
  4. Make your modifications, respecting the coding and design guidelines, and check that they don't break existing unit tests.
  5. Create a patch file and attach it to the JIRA ticket you created.
  6. The patch will either be validated or you will receive feedback with guidance to complete it.
  7. The patch will be committed by a Nuxeo developer.

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 being accepted. You will be prompted for the signature in the PR comments or you can browse https://cla-assistant.io/nuxeo/nuxeo

We'd love to hear your thoughts!

All fields required