By intention and design, dotCMS is an open source content management system which is fully intented to be useable and contributable by members of the open source development community. We strongly welcome and encourage feature enhancements and suggestions, code contributions, and identification of and solutions to problems found in the dotCMS code base.
However dotCMS is also a large and continuously evolving product and code base; we have multiple teams of in-house developers, regular customers and open source developers simultaneously contributing to the dotCMS code base literally every day. For us to manage this continuous and exciting development, we must manage the technical, business, marketing, and management aspects of coordinating such a large and active base of stakeholders.
Therefore, before you contribute to dotCMS (either directly or in the form of issue reports, suggestions, use cases, etc.), we request that you read through and follow the process outlined below. This will help us make sure your contributions are both fully recognized and quickly integrated in the most effective manner possible for both you and the dotCMS team.
Step 1: Please Notify Us First
If you wish to notify us of a potential issue with the product or submit a request for a new feature or change, you don't need to notify us separately - please just submit an issue report directly to our Github repository.
However if you wish to either suggest speific code changes in the existing code (either to provide a potential solution for an issue you've discovered, or to add or modify a feature), for the best results please tell us before you submit any code that you plan to contribute code to the dotCMS core project. Please contact us with the following information:
- Are you a current dotCMS customer?
- If so, please tell us your company name, your name, and if your company has an Enterprise license and/or support contract.
- What code, property, module, plugin or additions and fixes you plan to contribute to.
Note that you may notify us of your intention to contribute to dotCMS in several ways, for example:
- Contact account services.
- Contact us through the dotCMS support portal.
- Submit a github issue.
This information will greatly aid us by:
- Making sure that we have the right dotCMS staff aware of your contributions.
- Enabling the dotCMS team to map a dotCMS customer account and/or dotCMS user forum ID to your github userId.
- Ensuring that any of your existing dotCMS representatives can help guide your submissions through the process with the rest of the dotCMS team.
- While being a dotCMS customer or user forum member is not a pre-requisite for contribution, knowing that you are a customer or established community member helps us map a known use case to your code and can improve the chances that your code will possibly make it into the development branch for a later
Important Resources to Consult Before Submitting
dotCMS has many very active official resources in which the progress of both the product and future product plans are identified, documented, addressed, resolved, and continually updated. These include:
- The dotCMS Github repository.
- This includes information on the dotCMS agile development process, active code development, documented issues and feature requests, active code changes, roadmap information, and more.
- The dotCMS Roadmap.
- The dotCMS documentation site.
In addition, dotCMS has an engaged user community which provides help, feedback, and code via the following additional resources:
- A Code Share full of examples provided by both dotCMS staff and community users.
- A very active dotCMS user forum full of many very active and very experienced dotCMS developers and usrs.
Because of this, many issues, ideas, or features you may have for the product may have already been discussed, specified, worked around, or even completely solved in one of these existing resources. The dotCMS user forum, in particular, can often provide very quick and helpful information to implement specific solutions or solve specific problems without the need to delve into the dotCMS source code.
Therefore, if you are unsure how to address a particular issue, or have a need for a change or a new feature that you do not believe is currently supported by the dotCMS code base, we recommend that you first check these resources, and at the very least post a request for help on the dotCMS user forum before investing significant time and energy into inspecting and modifying the dotCMS code base.
Finally, note that for significant changes or additions to the dotCMS code base (such as the addition of new features, major changes or upgrades, etc.), dotCMS offers a special Directed Development program for our Enterprise customers, where dotCMS works closely with you to help define, implement, and eventually fully support changes to the dotCMS core product. For more information, please see the Directed Development program documentation.
Step 2: The Coding Process
To submit code to the dotCMS code repository (repo), please follow
Enter an issue in the dotCMS Github repo.
- This will allow you to reference all your code changes back to the issue, making it easy for dotCMS staff to connect the code changes with the purpose and description of the changes.
Fork the dotCMS core github repo (dotCMS/core) into your own repo.
- Note: For more information on how to fork a repo in Github, please see the Github documentation.
Make all your code changes in your own forked repo.
Commit your code changes into your own forked repo.
- When committing to your forked repo, please reference the dotCMS issue number created in step 1, above.
- For example, in your git commit command, enter a something like: `git commit -m “dotCMS/core#10456 fixes this thing” (or if you commit the change directly in Github, use the “dotCMS/core#10456 fixes this thing” message as the title line of the commit).
If you made your code changes locally, push your committed changes back to your forked repo in Github.
Step 3: Create a Pull Request
Create a pull request for the code changes from your forked repo to the dotCMS/core repository.
IMPORTANT: The pull request is critical, as it is the only way the dotCMS team will know that you have changes which are ready to be reviewed an considered for inclusion in the dotCMS core code.
dotCMS Contributor License Agreement
Please also note that all code contributions to the dotCMS code base must be accompanied by an agreement to the dotCMS Contributor License Agreement. The first time you do a pull request, the system will automatically ask you to agree to the dotCMS contributors agreement.
Important: No code will be accepted into dotCMS until after a committer has agreed to the Contributor License Agreement.
Step 4: Advocate!
The final step in getting your contributions noticed and on the way to being included in dotCMS is to advocate for your work. In the most simple terms, this just means that you need to make sure you communicate to the dotCMS team both the work you've done and why your changes are important (both why they're important to you as a dotCMS user and to the dotCMS user base and dotCMS team as a whole).
Everyone at dotCMS has many things to do, and even though you've already done the majority of the work to create, test and integrate your code into the dotCMS code base, all code changes require additional work, overhead and time from the entire the dotCMS team. This work and time takes the form of review, testing, documentation, support, management, and continued maintenance once your code is integrated into the core dotCMS code base - and all of this generally increases our workload. Even though your pull request might be bulletproof, clean, documented, well written, modern and well tested code, we still must double-check everything and integrate it into the product (both now and for all future versions!). So we ask that you “poke” the dotCMS staff to ask them to look up from their existing work and take notice. This is best done by advocating for your code.
Some of the following methods can be very useful and productive ways to advocate for your code:
- Contact your dotCMS account manager to discuss both the code and the reasons you made the changes.
- If you've fixed an issue, contact the dotCMS support portal and create a support ticket referencing the code and the issues it solves.
- Continue the conversation with the dotCMS engineering team on github via comments on the pull request you submitted.
- Post a message on the dotCMS user forum regarding your code.
Disclaimers
dotCMS makes every effort to continually improve our products and code in the best interests of all our customers. In fact, we literally work to improve our product and code each and every day. And we consider contributions from our user community a very valuable and vital part of that process.
Not All Submissions May Be Accepted
However there are many factors that affect what code changes are included into the product, and dotCMS makes no guarantees that any contribution, even if it fully follows the above process and provides value to the product, will be accepted into the software, Similarly, we can not guarantee that even if we plan to include any code contribution in the product, it will be included in a particular release. The benefit of any potential contribution will be weighed against the amount of debt and overhead that it adds to the software (both currently and for future maintenance) AND to the changes it makes to the current release cycles. If dotCMS does not accept your code, please feel free to ask us for an explanation or reconsideration via any of the above channels.
All Submissions Undergo Code Review and Multiple Degrees of Testing
If your code is deemed “Accept-worthy” by dotCMS, it will undergo multiple levels of both code review and testing. Based on the outcome, dotCMS might merge it wholesale, change the code, respond with questions or suggestions, take only subsections of the code, or choose to completely rewrite it. This level of review, testing, and possibly rewriting is necessary for us to maintain the integrity, security, compatibility, and maintainability of the code over the long-term life cycle of the product. However, if your contribution in any form is accepted and integrated into dotCMS it's a cause for celebration, as you've successfully turned the ship and contributed to a successful open source project. Your code has made it into the dotCMS core project, made a difference to multiple users, and you no longer have to support and update it yourself. Congratulations!
