ArchivesSpace Process for Evaluating Potential Feature Contributions to the Core Code

Owned by Christine Kim (Unlicensed)
Last updated: Feb 28, 2022 by Christine Di Bella
7 min read

ArchivesSpace is an open source community-supported application and anyone is welcome to make modifications to the code for their own installations or to offer code to others. This process is intended to guide evaluating code contributions that are offered to ArchivesSpace by developers and others outside the program. Its primary scope is for feature contributions only – items that add new functionality or change or extend existing functionality in a significant way. This evaluation process is separate and does not take the place of development done with program resources and prioritized by the Development Prioritization subteam.

When evaluating potential feature contributions to the core code, ArchivesSpace follows the process outlined below. If you’re considering developing a feature for the ArchivesSpace core code, we encourage you to get in touch with the ArchivesSpace program before initiating the evaluation process and to involve appropriate staff and community members as much as you can. Appropriate community members may include User Advisory Council or Technical Advisory Council subteams that specialize in a particular area, individual community members or archival community groups that have expertise, or just the community overall. The ArchivesSpace program team can provide suggestions if you are unsure who may be able to provide early feedback on your feature.

When you’re ready for step 1 of this process, please contact Christine Di Bella, the ArchivesSpace Program Manager, at christine.dibella@lyrasis.org.

1.   Determine the level of interest for the feature

Our first consideration is whether your feature is likely to be of interest to the wider ArchivesSpace community. This process involves the ArchivesSpace Program Team and the Development Prioritization subteam (a group made up of members of our User Advisory Council and Technical Advisory Council).

Some questions we may consider:

  • Has the community already identified the feature as being of interest, via a JIRA ticket, results of a community survey, or community discussion?
  • If the feature has already been identified as of potential interest by the community, what is its level of priority among the many development projects under consideration?
  • If the feature has not already been identified by the ArchivesSpace community as of interest, what criteria have you used to identify it as possibly of interest?
  • What use case(s) does the feature seek to support?

You may want to gauge interest before bringing your feature up for consideration by ArchivesSpace by posting to the Users Group listserv, ArchivesSpace Google Group, or in other community forums, or by creating a JIRA ticket and asking people to comment on it.

If a compelling need cannot be shown, or if the interest is very limited or very specific, ArchivesSpace may advise you that the project may be most appropriately handled as a plugin or localized development work. In such cases, we will also encourage you to share your development with the wider community when possible. One option for doing so is archivesspace-labs: https://github.com/archivesspace-labs. The ArchivesSpace community is large and diverse, and though the standard distribution application understandably cannot include all potential features, any customization done for one institution may potentially be of interest to others.

2.   Review functional specifications

Next, or in conjunction with Step 1 if it is necessary in order to determine level of interest, the ArchivesSpace Program Manager and relevant community members (who the community members are will depend on the specifics of the feature) will review the quality and completeness of any functional specifications and documentation. If there is not a functional specification, for projects for which a compelling interest has been identified, the ArchivesSpace Program Team may be able to identify community members who would be willing to work with you to create one.

A good functional specification should include information such as:

  • The use case(s) you’re addressing
  • How you envision the feature working from a functional standpoint, and how this differs from how it works in ArchivesSpace currently (if applicable)
  • Reference to archival or other standards the feature will employ
  • Wireframes or mockups

Some examples of functional specifications are included on the Integrations subteam’s page How to Integrate with ArchivesSpace: https://archivesspace.atlassian.net/wiki/spaces/ADC/pages/102471870/How+to+Integrate+with+ArchivesSpace. One example of a template that has been used for past specifications is: https://web.cs.dal.ca/~hawkey/3130/srs_template-ieee.doc

If there is information missing from the functional specifications and documentation, the ArchivesSpace Program Manager or community members may be able to help in fleshing them out. Until the functional specifications are clear, it will be difficult to put together an implementation plan, so we strongly encourage you to put as much effort as you can into the functional specification, and reach out to us if you need help.

3.   Review technical implementation plan

Next, the ArchivesSpace developers, the Core Committers group, and relevant community members will review your implementation plan. This does not need to be a formal written plan, but there should be information on some or all of the following items when submitting a feature for consideration from a technical perspective:

  • Coding approach and standards for development
  • Indication of any anticipated data model changes
  • The impact, if any, on the master branch and other enhancements/bug fixes currently being worked on
  • Testing level, including how and for what automated testing will be implemented
  • Names of participating developer(s)
  • Links to Github repositories for the developers or that are being used for the feature
  • Information about plans for sprints, and whether ArchivesSpace Program Team or community members would be welcome to attend as observers or commenters
  • Timeline for development
  • Anticipated date for inclusion into master branch

If you do not yet have an implementation plan, or if you cannot provide this kind of information, the ArchivesSpace Tech Lead and Core Committers can advise on a technical approach as needed.

While the primary basis for determining whether a feature is suitable for the core code is functional, there is a chance that the technical review will yield information that indicates that the feature is more appropriate as a plugin, including as a plugin that comes with the standard distribution of ArchivesSpace. In such a case, the Tech Lead and the Core Committers will advise you on how to create the plugin so that it can work as seamlessly as possible with the core code.

4.   Gather community input on specifications

While we encourage you to seek community input on your feature even before bringing it forward for consideration by ArchivesSpace, once all the specifications and plans have been reviewed by the ArchivesSpace Program Team and relevant community members and deemed sufficient, ArchivesSpace will work with you to gather greater community input.

  • We will work with you to distribute via the listservs or monthly updates the specifications and information about the feature to the larger community in order to give more people the opportunity to provide suggestions, identify gaps, and/or test it out (if it is already in the process of being developed).
  • If a JIRA ticket does not already exist for the feature, the Program Team will create one and include it in any publicity or distribution about the feature going forward. You or your team will be assigned as the developers for the ticket.
  • Once feedback or testing data is received, the ArchivesSpace team can work with you to determine whether any adjustments should be made.

5.   Communicate with the community

Once the feature has been determined to be appropriate for the core code, the specifications and technical plans have been vetted by ArchivesSpace and the community, and a timeline is in place, the feature will be included on the ArchivesSpace technology and development roadmap (https://archivesspace.atlassian.net/wiki/spaces/ADC/pages/18710568/Road+Map) and progress on it announced via monthly updates or in posts to the listservs as appropriate. Regular updates on progress, to both the ArchivesSpace Program Team and the community, will be greatly appreciated. Depending on the timeframe for development, we suggest quarterly updates, at minimum.

If you’ve made it through Step 5, congratulations, and thank you! We look forward to receiving your feature for inclusion in the core code. The following steps will complete the process.

6.   Develop your feature and test it

Follow the guidelines at https://archivesspace.atlassian.net/wiki/spaces/ADC/pages/39682053/Submitting+a+Pull+Request to fork the code and keep it in sync with the master branch while you work. We encourage you to identify a product owner (a person who will determine when your feature is ready from a functional perspective) and do as much internal testing as you can. A very simple feature may only require a little bit of review at the end of development; a more complex one may require significant back and forth to hone and refine your work. If you haven’t identified a product owner or testers, the ArchivesSpace Program Team can often link you up with community members that are particularly interested in your feature and may be willing to test it or even serve as the product owner.

7.   Submit your pull request

Once you’ve finished development on your feature and feel it’s been sufficiently tested, submit a pull request following the instructions at https://archivesspace.atlassian.net/wiki/spaces/ADC/pages/39682053/Submitting+a+Pull+Request. Update the JIRA ticket to indicate that the code has been delivered. We encourage you to create user and/or technical documentation to go with your feature, and to submit that along with your feature. The ArchivesSpace Tech Lead will review the pull request from a technical perspective and let you know if any additional work is needed before merging. Once it’s been reviewed, the Tech Lead will merge it into the core code. Then the Testing subteam will do release testing on it, along with other features and bug fixes the ArchivesSpace Program Team has slated for the next release. If any problems are noted, that information will be passed along to you. The ArchivesSpace Tech Lead and Core Committers may be able to work with you to resolve any issues.

8.   Once it has been sufficiently tested, your feature will appear in a release of ArchivesSpace

Once your feature has cleared testing, it will be added to the list of tickets that will be included in the next release of ArchivesSpace. You will receive attribution in the release notes and release announcements. Rest well knowing that the ArchivesSpace community appreciates your contribution and start dreaming up your next development project!