Difference between revisions of "Development/Recommendations"

From AtoM wiki
(Add initial page content)
(No difference)

Revision as of 10:56, 19 May 2017

Main Page > Development > Development/Recommendations

Thank you for your interest in AtoM development, and for your willingness to share the code back with the community! The advantage for you is that when Artefactual accepts pull requests and merges your code into a public release, we also take on the feature’s maintenance through subsequent releases - meaning you don’t have to maintain it yourself, and re-merge it into your AtoM instance every time you upgrade to the latest release. Additionally, you are improving AtoM for all users!

Seealso

Read more about the AtoM project's history, how we maintain the application, and our business model here:

Below are a few resources to get you started working with AtoM, followed by some recommendations from our developers on how best to submit your work for inclusion in an AtoM public release.

Initial development resources

You will find an overview of the elements that make up AtoM, and a tour of the AtoM code, in the following resources:

AtoM was originally developed using the Symfony 1.x framework, and the Propel 1.x ORM. You might want to familiarize yourself with Symfony before beginning:

Symfony 1.x documentation: http://symfony.com/legacy/doc

AtoM also currently uses Elasticsearch 1.x for its search index, Twitter Bootstrap 2.3.2 for theming, and several other libraries. MySQL is used for data storage. We keep all our code in a git repository, so being comfortable with git or other distributed version control systems will also help you. There are a lot of resources out there on all of these!

We maintain a Vagrant box that can be used for local development - see:

If you are interested in theme development, we have a basic tutorial available in our documentation to get you started, along with some slides:

We’ve also got a number of other development resources on our wiki - be sure to check them out as well!

Seealso

Contributing code to the public project

We welcome code contributions to the public AtoM project - the Contribute code page on this wiki will outline the basic steps when you’re ready to submit your code, while the Coding standard page will offer some guidance on some of our particular style preferences. Our Code review page explains why we feel that code review is important, and what you should expect from the process. Below are some more general tips for community developers who are working on feature development, and who are considering submitting code to the public project:

1. If you’re starting a new development project, we encourage developers to open pull requests early, to get feedback during the development process, rather than when a project is complete and it is more difficult to allocate time for changes. Clarify that a pull request is a draft or a work in progress, and make a post with further invitation in our User forum - our developers and other community devs can then offer some initial guidance that might save time later!

2. We greatly value having some simple comments in the code that help to explain what your code is doing and why - this helps us maintain your feature through subsequent releases, and allows new developers to better read your code! No need for overkill, but a well-placed comment throughout can save us a lot of time, help with future debugging and additional development, etc.

3. Before submitting any code, please make sure you pull in our most recent development branch, resolve any conflicts, and do some basic testing to make sure the feature will work in the latest release. For example, perhaps you developed a plugin against your local 2.2 instance, and now, a year or two later, want to submit it to the public project so you will be able to upgrade without having the handle maintaining the plugin locally. We have done a lot of development since the 2.2 release (some indications of upcoming changes can always be found on our Roadmap page), some of which may include major changes to several key modules, and therefore could affect your work! We expect new features to take into account these factors before being submitted.

4. Is your work based on any existing open standards? We try to keep any areas of the application that can relate to existing standards based on those - if yes, please point us to the relevant standard. If not, and a standard exists at the international level (or possibly, at the national level, etc), please consider how the work might be modified to it adheres to known best practices and standards within the cultural heritage community. Remember as well that the standards must be open to properly work with our license and distribution.

5. In general, we recommend that developers adding modules or large features to AtoM follow Symfony's plugin development model. Most of the existing modules in AtoM and ICA-AtoM have been built as plugins. You will find much on plugin development for the Symfony 1.x framework (which AtoM uses) in the Symfony documentation - namely:

6. Spend some time reading existing AtoM code - especially in areas of the application that relate to the work you are doing. We’re aiming for consistency, which helps us better maintain the application - and also efficiency, by reusing existing methods and functions whenever possible. Familiarizing yourself with how similar problems have been solved elsewhere in the application can save a lot of time later during the code review process.

7. For large pull requests, we greatly prefer if these can be broken up into atomic commits, so that our developers can review each change and its rationale incrementally and make specific change requests for any section that does not work. As a small company who manages all community releases free of charge, this also helps us balance the review work with the client commitments we must maintain if we are going to be able to continue to support AtoM as an open source project.

8. Expect to make changes, and budget time accordingly. When our developers review and approve community submitted code, we are taking on the maintenance of the feature through subsequent releases, which entails a lot of testing, review, bug fixing, documentation, and community support. This means our team needs to ensure it follows existing design patterns and can be readily understood and maintained by our devs. For those starting new projects, we strongly recommend that you budget extra time in your project for the code review process, including changes. Please don't take it personally or be discouraged if we ask for changes, and thank you for understanding!

9. There are some features that may not be desirable to all AtoM users. Our usual recommendation in this case is that they be made configurable - either as a truly optional plugin that can be turned on or off, and/or as a setting in the Admin section, where users can control whether or not the feature is enabled, or how it is enabled. In general, we encourage you to think beyond your particular use case during development, to think about how the feature or module will impact AtoM as a whole and be designed in such a way that it not only meets your needs, but can be of benefit to all AtoM users.

10. Please be aware that we do not accept all pull requests. It depends on the ability of the submitters to conform to the vision of the project, and recommendations stated in this email and supplied by our developers during code review. In cases where we are unable to merge the code as is, we are happy to list the work on the Community development section of our wiki, so we can encourage other users to fund the work we feel would be necessary to merge the feature into the main public branch - and so developers can access the code and make their own local customizations as desired. You can see some examples of this in the Community Development section of our wiki.

Thank you so much! If you have questions, feel free to post them in the AtoM User forum. We look forward to collaborating with you!

Retrieved from "http://wiki.accesstomemory.org/index.php?title=Development/Recommendations&oldid=1644"

Account

Page

Search