Here are a few tips and best practices to follow when creating an Aras Community Project.
Do: Include Your Source Code
All Aras Community Projects must include the original source code. For example if you create an external application that interacts with Aras, you will need to provide the project source code in addition to any compiled code (dll’s, executables, etc). This is critical to sustaining a strong open-source community where members can grow and collaborate together.
Do: Use Innovator\Client\Customer
If you do need to include custom code tree files, such as an external HTML file or a folder of icons, it's best practice to place the files under the
Innovator\Client\customer directory. This keeps custom files organized in one place and helps prevent them from being overwritten or lost during upgrades.
Files in the
Innovator\Client\customer folder can be accessed via relative path, or via direct path such as http://localhost/innovatorserver/Client/customer/myFile.html or http://localhost/innovatorserver/Client/customer/myIcons/myIcon.svg.
Do: Use a Custom Package
Many Community Projects include a package to import customizations into a target Aras database. When creating these export packages, it's a good idea to create a project-specific package rather than adding customizations to an existing Aras package. This makes it easier to export custom items and reduces the risk of overwriting customizations during upgrades.
For example, say we are packaging up a project that includes custom ItemType, List, and Method items. The project also modifies the built-in Categories List item to allow the new ItemType to appear under a new Category in the TOC.
Custom items are added to the Aras package 'com.aras.innovator.core'.
- Custom List
- Custom ItemType
- Custom Method
Custom items are added to a new package, separate from any Aras platform or application packages.
- Custom List
- Custom ItemType
- Custom Method
There is no required naming convention for custom packages, but an easy one to remember is '<GitHub username>.<repo name>'. If your project is not hosted on GitHub you can use your name or company name. This allows users to quickly determine which package(s) in a database belong to a given project.
Do: Use Version Control
Using version control like Git provides numerous benefits. You can track iterative changes to your code, concurrently collaborate with other contributors, and take advantage of open source code sharing platforms like GitHub, GitLab, BitBucket, etc.
Do: Document Your Project
When it comes to documentation, we really want to see three things:
What does it do?
Describe what the project does. Is it designed to solve an industry-specific business problem? Does it streamline administrative tasks or enhance existing Aras functionality?
How do you install it?
Instruct the user how to install your project, from the point they download it to when the project is ready for use. Don’t forget to mention any preconditions/prerequisites for the target Aras instance (ex: Tech Docs must be installed to Aras, or the server must have Visual Studio installed).
How do you use it?
Give the user the basic steps to use the project, starting from login.
Your project documentation doesn’t have to be a lengthy PDF or hefty MS Word doc – Aras Labs projects are documented using the README.md found in the root of every GitHub repository. Check out any Aras Labs project for an example, or feel free to use this readme as a template.
Do: Credit Contributors
Be sure to give credit where credit is due. If you collaborated with a team to spec out your project, or if you partnered up with a colleague to write the code, give them a shout-out when you submit it. And don’t forget to recognize any third-party vendors, developers, or designers whose work you may have used, especially if their license requires it.
Do: Include a License
Visit https://choosealicense.com/ to try out GitHub's tool for choosing an open source license for your project.
Tell community members how they are allowed to use your code by including a license with your Aras Community Project. All Community Projects created by Aras Labs are published under the MIT license. If you are unsure which open source license is right for your project, check out ChooseALicense.com, a handy tool created by GitHub to explain the various open source licenses.
Do: Spread the Word!
Once your Aras Community Project is published, share it! We'll send you a link to the project's post on the Aras Community Projects page that you can share with your colleagues, Twitter followers, LinkedIn connections, etc.
To stay up-to-date on the latest Aras Community Projects, blogs, and news from Aras Labs, follow us on Twitter.
Ready to Submit a Project?
Head on over to http://community.aras.com/share-a-project/ to submit your project for review. Looking for inspiration or not quite ready to submit a project of your own? Check out the Aras Community Projects page at http://community.aras.com/projects/ to see what other community members have been working on, or even contribute to an existing project.