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
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 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).
There are two ways to contribute:
- By cloning the GitHub repository locally and using command line.
- By using GitHub UI and make your changes online.
Clone the GitHub repository:
git clone https://github.com/nuxeo/nuxeo.git
Ensure the branch you’re working on is up to date:
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'
Open your favorite IDE and apply your changes.
Add your changes on git:
git add -A
Add a commit message, respecting the naming conventions
<TICKET_NUMBER>: <description lowercase>:
git commit -m 'NXP-28804: add quick filter for docs in retention'
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
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:Pull Request ReviewYour 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.
(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
- Prefix the second commit message with
- Push force the modification:
git push --force
- And repeat it until there is nothing left to review!
- To merge and rewrite your commit, run
Once your contribution is approved, go to your PR on GitHub, click on Rebase and Merge button.
If you need to edit a single file, you can use the default GitHub UI feature to create a pull request.
Click on the edit icon:
Make your changes and add a commit message, and update the branch name respecting the naming conventions:
Don’t forget to Test and Push (T&P) after getting the number of required approvals (manual operation needed for now).
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.
Nuxeo labels are stored in ASCII files. We use the UTF-8 encoding for non ASCII files (like
é). You have two different options.
See HOWTO: Translate the Nuxeo Platform for more details.
- 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.
For now, English translations are managed only on GitHub.
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
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. Don't hesitate to contribute directly to the GitHub repository.
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.
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.
- Create a JIRA "Contribution" ticket that will hold a description of your improvements, functionally and technically.
- 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 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.
- 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 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.
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).
- 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.
- 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