ArchivesSpace re-org and committer groups proposal
How to Report a Bug
How to Request a New Feature
How to Contribute Code or Documentation
How to Participate in Community Release Testing (forthcoming)
Creating User Screencasts
Sally = purple
Max = orange
Dave = Blue
Green = group call notes
Brown = Esmé
Propose creating / maintaining these organizations:
Most documentation should be in confluence wiki & links in Github readmes.
Contains the core ArchivesSpace repositories, including the main project and migration tools. All code here is officially supported and maintained by at least the ArchivesSpace Program Team.
ArchivesSpace is open source and released under ECL, v 2.0. The software and associated documentation is developed collectively by a community of contributors and committers. All interested community members are encouraged to contribute to the project. Contributors who demonstrate sustained engagement with the project through quality participation in meetings, mailing lists, documentation and code updates can be nominated by existing committers to also become a committers. It should be emphasized that committers need not be limited to software developers. Community members with skills in documentation and testing, for example, can also be committers.
Committers share the following rights:
Committers share the following responsibilities:
Committers are encouraged to speak with their organizations to clarify how contributions to the ArchivesSpace community fits into their role and what amount of time can be dedicated to contributing to the ArchivesSpace community.
The following is an alphabetized list of the current ArchivesSpace committers:
A full list of all known community and emeritus contributors can be found here.
ArchivesSpace Committers Calls are monthly meetings of the developers of ArchivesSpace, who discuss modifications and innovations in the code, and review new and open tickets. Calls are open to interested
This section describes the process for handling the voting of a new committer. Voting is handled by emailing the Committer List.
If they accept, then do:
When a contributor is nominated to become a committer, the following guidelines should be used by existing committers to evaluate the nominee's suitability:
Note - have excerpted text here but just may want to keep this as a separate page as is - have included here so we can review & make final decisions - e.g. the travis / jenkins issue?
Find or create a bug report or feature request ticket in JIRA GitHub (to make sure you’re not duplicating work and document the intent of your contribution). It helps to explain both the existing behavior and the desired behavior that your change will implement.
Set up a GitHub account if you have not done so before.
Fork the ArchivesSpace repository on GitHub.
Create a feature branch.
Make changes in your fork. We advise contributors to follow these guidelines to expedite the contribution review process.
Follow established style guidelines
Include unit tests sufficient to cover the feature(s) you add or bug(s) you fix, and make sure the test suite passes. (Can we rely upon Travis or a Jenkins instance for this, or should we suggest that contributors run tests locally?) → would be good to run travis locally
If you’re adding a feature or otherwise changing documented behavior, modify the documentation to reflect your changes.
Once your work is done, squash the commits in your branch — see One Commit per Pull Request for some guidelines — and rebase it on the latest in the upstream master branch. We appreciate succinct but explanatory commit messages.
Push your updated branch to your fork.
Create a Pull Request on GitHub.
Respond to feedback as the community reviews your contribution.
There is some work on these kinds of contributing guidelines going on in the Hydra community right now, here are some updated docs that might have some good stuff to include here:
Encourage smaller contributions and smaller pull requests in sequence when possible.
Before you start, make sure you're talking to people – use email or Github issues?
may need to use multiple channels anyways
ACTION - merge this kind of doc w/ the Core Contribution Guidlines
0. Share Early, Share Often!
The overriding mantra is share early, share often. Here are a few things to consider before you begin working on your code:
Once your code is ready, you must make your code available to the ArchivesSpace Committers Group for review. The easiest way for us to review your code is by putting your code into GitHub (just create your own account – it's free!). Then, submit a "Pull Request" to our GitHub repository (see Development with Git). Alternatively, if you are not yet comfortable with GitHub, you may create a patch (and upload it to our DSpace Issue Tracker). However, please be aware that submitting a patch may delay the review process (see below note)
In either case, you must also create a new ticket in our ArchivesSpace JIRA Issue Tracker. This ensures that the ArchivesSpace Developers are notified of your contribution, and acts as a place for us to comment on the work or make suggestions for improvements. (is this the right process for us?)
Once the code is made available, the Committers Group will take time to review the work and provide feedback/comments. Code must be reviewed by at least one other committer from another organization before it can be merged.
Usually, one (or more) committers who are interested in this work will contact you and discuss any feedback we have, and whether or not there would need to be some general changes before we could accept it. Some patches/features are readily accepted (because they are stable and look good), others may require more work (if there are concerns or issues that Committers notice).
The timeframe of a code review will vary, based on how much time the Committers have. Smaller changes may be reviewed within days, while larger changes/features may take many weeks to do a full review. All Committers are volunteers and only have a small amount of time to provide to the project in a given week. We will make every effort to get back to you with feedback within a few weeks. But, if you haven't heard anything, feel free to ask! (is this the right process for us?)
We'll also want to define 'rights and responsibilities' of core committers that specify good practice such as not merging your own code, etc. <--- Fedora has a good 'rights and responsibilities' doc that we can probably use as a model. (this one: https://fedoraproject.org/wiki/Package_maintainer_responsibilities??)
After the code review & feedback, interested Committers may help you to rework the code (if needed). They'll also provide you with next steps on getting the code into ArchivesSpace. If it can be accepted immediately, it will be. If not, we'll try to help figure out the best route forward.
How you can help speed up the process
As our Committers are all volunteers, they don't always have the time to rework code changes for you. If you want your code change accepted in a timely manner, please offer to make the changes yourself (otherwise your patch suggestion may wait in a "holding queue" until someone has enough time to work on any necessary fixes).
If you are unsure of next steps, please let us know by adding a comment to your issue in the Issue Tracker. Communication is absolutely necessary to ensure that we can help you rework anything that needs reworking. If we don't hear from you, we'll assume you are hard at work. So, if you've run into issues, please let us know! If, locally, you don't have the time or expertise to do the rework that is necessary, also let us know. We can try to locate a community developer to help out, and/or ask both the Committers Team and the ArchivesSpace Community Advisory Team if they know of any interested developers with time to spare.
Once your code is accepted, it will be released in the next version of DSpace software! It is time to celebrate, as your name will be added to the prestigious list of DSpace Contributors!
General discussion notes:
Oversight for the core committers comes from the Program Team developer(s) and other established core committers ... Islandora - has text about this; but doesn't start from scratch
Sally's thoughts on structuring this documentation from looking at other OSS community examples:
Purpose: contains plugins officially supported by at least the ArchivesSpace Program Team.
These plugins are tested and updated as necessary to be compatible with new releases.
Provides a focal point to discover plugins and contribute to their development.
I wrote something up here: https://docs.google.com/document/d/1a_4AEgXHHZnbKWwjRcEVw8FWdme1cldKWvII9cLRYxI/edit?usp=sharing
Purpose: contains proof of concepts, examples and experimental projects. There is no official
support from the Program Team for anything in labs. The projects are not guaranteed to be up
to date with the latest release and are used on a atyourownrisk basis. Program Team and
other “official” committers can contribute to labs but that does not confer official support to any
project. Note - Labs branding should make it clear that none of the projects are officially supported.
(Core committers? Committers Oversight?) will conduct a early review of archivesspacelabs and will move clearly abandoned or obsolete code to deprecated.
Maintained by: Community Committers.
As far as I know, there's currently no automated way to say "this fork is a reference, keep this fork up to date with its parent." Thus, anything forked in to this org will need more or less constant maintenance, or some sort of scripted update mechanism, in order to maintain currency. Given that this seems primarily intended as a linking mechanism to externally provided code, would it maybe make sense to have the primary entry point into this be a Github Pages page, with a link to each internal/external tool and other explanatory content. I think the barrier to entry won't be any higher than with a collection of forked repos, and the maintenance burden would be lower.
As per the notes from last time, since we're trying to encourage "as much collaboration, sharing and committing as possible," it might be nice to lower barriers if we had some resources readily available from this space. I'm not suggesting we create any, just point to existing guidelines/tutorials on GitHub lingo, getting things in there, best practices for READMEs (even if we aren't requiring any documentation), etc., who to ask for help, etc.
A good example to follow here is the IIIF Awesome repository. It contains only a README with links to IIIF examples and resources, and contributing guidelines. So instead of having a whole GitHub organization, this would be a repo (in the main archivesspace org?).
Group liked the IIIF Awesome repository and what Max has developed as a model.
Github Organization Blurb: Experimental, example, and proof-of-concept projects. Feel free to start new collaborative projects here, or add a link to external projects to the Cool ArchiveSpace Projects README. Projects are not guaranteed to be compatible with the latest release, or officially supported by the ArchivesSpace Program Team (though Program Team members may contribute).
Purpose: contains repositories that should no longer be used with ArchivesSpace or that have
become generally obsolete.
Maintained by: Program Team, Core Committers.
Community Committers: Any developer wanting to contribute a project to labs or work within it.
Access to labs (write access).There are no minimum requirements for adding resources to labs. Adherence with y coding guidelines and inclusion of some documentation is encouraged but not required.
Need to decide how labs will work. Will it be forking external projects or encouraging developers
to work within it directly and transfer existing projects to it? Former is more hands on and will
require keeping the forks up to date, latter may be harder to get buyin (devs can also do both
quite easily by adding labs as an additional remote should probably encourage that for devs
who want to maintain control, but can also push to labs).
About the forks: would we have to keep forks up-to-date? Could that be part of the yearly review to see if things get deprecated (would that be too much)? I like the idea of encouraging devs to make it a remote.
Process / criteria for adding new members:
Oversight for the community committers comes from TAC (a new subgroup or the existing
comitters oversight group?). One member of the subgroup will be responsible for adding new
members (should be a committer or promoted to one?). Criteria for new members? Anyone who
To deprecate a repository it must first be announced to the mailing list for input. If there are no
objections then the the Program Team Manager should confirm the status.With approval the
repository can be transferred into deprecated two weeks after the initial message.
If there are regular tech team meetings it can be raised.
Actions from September 14th, 2016 call:
Actions from previous calls:
Actions from November 7th, 2016 call:
Possible to stage implementation? - Yes