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:
- Important development choices can be followed on through the tech reports. 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,
- Quality of the product development can be monitored on our Jenkins Continuous Integration site and SonarQube Quality Assurance site.
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 totally 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.
There will be a "contributions portal" in the future; until then, this page explains the process that should be respected.
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.
- Any evolution in Nuxeo sources should be matched with a JIRA issue (http://jira.nuxeo.com/browse/NXP, or corresponding product NXMOB, NXIDE, NXBT...).
- Any code evolution must be documented, in the English language.
- 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 design code could be rejected.
Nuxeo labels are stored in ASCII files. We use the UTF-8 encoding for non ASCII files (like
é). You have two different options. See How to 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 JSF UI labels, looking at the reference messages.properties file at 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
addonsdirectory, 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.
Contribution is welcome both for technical (books and guides, FAQ, tutorials) and functional documentation. Ask a contributor account for http://doc.nuxeo.com on Nuxeo Answers, the nuxeo-dev mailing list or on the Nuxeo Google+ community.
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.
- 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 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. Process is 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.
- Create a JIRA "Contribution" ticket that will hold a description of your improvements, functionally and technically.
- Send an email to the nuxeo-dev mailing list, or post on the Nuxeo Google+ community, to notify the community as well as Nuxeo developers.
- 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.
- Read the Coding and design guidelines.
- Fork the project on GitHub.
- 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.
- Send a pull-request.
- In JIRA, set the ticket to "devReview" state and give a link to your pull request.
- Finally, we can ask for some changes, putting comments on your code, then your branch will be merged by a Nuxeo developer.
Nuxeo is highly modularized and as a consequence, it is totally possible to develop a new feature that will be deeply mixed with 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 a web page (Wiki) and a JIRA project for the visibility of your development.
- Start by an introductory email in the mailing list, explaining 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 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.
- You can ask for a code review in the nuxeo-dev mailing list.
- 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:
- Create a JIRA ticket of type "Contribution" describing the problem and what you plan to do (or what you did, if it comes after).
- Send an email to the nuxeo-dev mailing list, or post on the Nuxeo Google+ community, to notify the community.
- Read the Coding and design guidelines.
- Fork the "master" branch of the sub-project you want to patch.
- Make your modifications, 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 ticket you created.
- Send an email to nuxeo-dev mailing list to notify the community of your contribution.
- 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.
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