Aras Best Practices: Community Projects, Part 1

Aras Best Practices: Community Projects, Part 1

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.

Incorrect

Custom items are added to the Aras package 'com.aras.innovator.core'.

  • com.aras.innovator.core
    • List
      • Categories
      • Custom List
    • ItemType
      • Custom ItemType
    • Method
      • Custom Method

Best Practice

Custom items are added to a new package, separate from any Aras platform or application packages.

  • com.aras.innovator.core
    • List
      • Categories
  •  elijdonahue.My-Custom-Project
    • List
      • Custom List
    •  ItemType
      • Custom ItemType
    •  Method
      • 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

Image Source: http://www.amarinfotech.com/gitlab-vs-github-vs-bitbucket.html

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

http://choosealicense.com/

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.

Aras Labs (@araslabs) | Twitter

The latest Tweets from Aras Labs (@araslabs). Aras Labs is the @aras_plm R&D team. We build innovative apps and services to shape the future of PLM. Find our open-source code at https://t.co/Wa1h8VGosR

Ready to Submit a Project?

Head on over to https://community.aras.com/i/projects 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.