-
Notifications
You must be signed in to change notification settings - Fork 99
Governance
- Mission of ActivitySim
- Roles & Responsibilities
- Project Management Committee
- Decision Making
- Communication Channels
- Code Management
- Contribution & Acknowledgement
The creation and maintenance of an advanced, open-source, activity-based travel behavior modeling software based on best software development practices for distribution at no charge to the public.
The primary purpose of this endeavor is to unify the best practices in activity-based travel models for transportation policy analysis and reducing the cost of ownership for public agencies.
ActivitySim is a meritocracy with the following roles:
A user is someone that uses ActivitySim. They contribute by providing feedback to developers in the form of bug reports and feature suggestions. Users participate by helping other users.
A developer is any user who contributes to a project in the form of code or documentation. They take extra steps to participate in a project, are active in the online development discussion, provide patches, documentation, suggestions, and criticism.
A committer is a developer that was given write access to the code repository and has a signed Contributor License Agreement (CLA) on file on the project GitHub site. The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to ActivitySim and thereby allow us to defend the project should there be a legal dispute regarding the software at some future time. Not needing to depend on other people for the patches, Committers are actually making short-term decisions for the project. The Project Management Committee (PMC) can (even tacitly) agree and approve it into permanency, or they can reject it.
A funder is an organization who contributes at least $35,000 in the past 12 months to the ActivitySim Development Fund managed by the AMPO Research Foundation. The Fund is used to pay for software development, including project administration and documentation as needed, and can be performed by Developers and/or Committers.
PMC membership is based on merit. Until December 31, 2021, merit is determined by contributions of funds to the ActivitySim Development Fund, and thus the initial PMC members are the funders. Ultimately, the PMC will evolve to include developers or committers that are elected due to merit based on the contributions of code to support the evolution of the project and demonstration of commitment to the project. PMC members have write access to the code repository, the right to vote for the community-related decisions and the right to propose an active user for committership. The PMC as a whole is the entity that controls the project, nobody else. In particular, the PMC must vote on any formal release of their project's software products. The PMC makes the decisions, not the individual committers.
The PMC chair is a PMC member whose sole additional responsibility is to manage PMC voting. This includes announcing votes, setting timeframes for votes, identifying the type of approval required (if not readily apparent), ensuring that a quorum is established as required by the type of approval, and adjudicating disputes about the validity of vetoes.
The PMC shall elect from among its members a Chair and a Vice Chair of the Committee. The Chair shall be responsible for conducting the meetings of the PMC and fulfilling such other responsibilities as the PMC may prescribe. In addition to assuming Chair responsibilities in the event they are absent or incapable of fulfilling them, the Vice Chair will actively participate in the below duties alongside the Chair:
- Manage PMC voting. This includes announcing votes, setting timeframes for votes, identifying the type of approval required (if not readily apparent), ensuring that a quorum is established as required by the type of approval, and adjudicating disputes about the validity of vetoes.
- Work with AMPO staff to provide oversight of annual budget and work to oversee administrative tasks such as (contract and task order award, invoice, etc)
- Work with AMPO staff to ensure execution of MOAs and funding agreements.
- Ensure any other regular administrative activities are occurring
The PMC contractor is the lead organization contracting with the AMPO Research Foundation to provide ActivitySim software development, project administration and documentation services.
Initially, the group of PMC members are the funders. Ultimately, the PMC will evolve to include developers or committers. PMC members can be as active as they choose, with no pressure from the project. People can be quiet and speak up occasionally when they see a topic that motivates them enough to contribute to the discussion or to cast a vote. Individual PMC members do not need to be involved in every aspect of the project. As a group, the PMC will maintain sufficient oversight.
The responsibilities of the PMC include:
- Be familiar with these project guidelines
- Support oversight of the commit log messages and ensure that the codebase does not have copyright and license issues, and that the project is heading in the desired direction.
- Support oversight of the development community resources to ensure that the open development ideals are upheld. Resolve license disputes regarding products of the project, including other supporting software that is re-distributed.
- Develop and managing a roadmap for new features and product enhancements that will be considered for each product release, determining release plans and approving official releases..
- Guide the direction of the project.
- Strive for and help to facilitate a harmonious productive community.
- Nominate new PMC members and committers.
- Support maintenance of the project's shared resources, including the codebase repository, issue management, websites.
- Speak on behalf of the project.
- Maintain these and other guidelines of the project.
The PMC can discuss certain issues in private. However, every effort is made to conduct all discussions in public.
Membership of the PMC is by invitation only and must receive consensus approval of the PMC members. The PMC elects a chair by simple majority. This chair is empowered to make determinations in breakdown situations and those requiring unanimous consensus, if this consensus cannot be reached within timeframe.
A PMC member is considered "emeritus" by their own declaration, e.g. perhaps personal reasons. Please send a note to the PMC and we will follow up to request acknowledgement of the Board. An emeritus member may request reinstatement to the PMC. Such reinstatement is subject to consensus approval of the PMC members. Membership of the PMC can be revoked by unanimous consensus of PMC members (other than the member in question).
At the direction of the PMC, the PMC contractor may act on behalf of the PMC.
- Joe Castiglione, SFCTA (Chair)
- Stefan Coe, PSRC
- Wu Sun, SANDAG
- Guy Rousseau, ARC
- Lisa Zorn, MTC
- Jilan Chen, SEMCOG
- Alex Bettinardi, Oregon DOT
- Dennis Farmer, Met Council
- Mark Moran, MWCOG
- Rebekah Straub, Ohio DOT
When new people are committed and consistent, PMC members will discuss each case to ensure that the PMC is in agreement. The private vote among the PMC is to enable a frank discussion and so that we do not conduct public discussions about people. Ultimately, new committers should ideally also become new PMC members as well. Otherwise they do not have a binding vote and so we would create classes of committers. When invited, a new committer is permitted to choose not to be on the PMC.
Different types of decisions require different forms of approval. This section defines how voting is performed, the types of approval, and which types of decision require which type of approval. Most day-to-day operations do not require explicit voting - just get on and do the work. See the "Lazy approval" type described below.
Certain actions and decisions regarding the project are made by voting by PMC members. Where necessary (e.g. discussion and vote about specific people to be new committers) PMC voting may take place in confidence. Presentation and discussion of the proposal should have happened prior to the vote. Voting is carried out via GitHub? Votes are expressed using one of the following symbols
| Vote Type | Description |
|---|---|
| +1 | "Yes," "Agree," or "the action should be performed." |
| -1 | “No,” “Disagree,” or “the action should not be performed.” On issues where consensus is required, this vote counts as a veto. All vetoes must contain an explanation of why the veto is appropriate. Vetoes with no explanation are void. It may also be appropriate for a -1 vote to include an alternative course of action. |
| Abstain | People can abstain from voting. They can either remain silent or express their reason. |
Different actions require different types of approval:
| Approval Type | Approval Requirement |
|---|---|
| Consensus | Majority of PMC “+1” votes and no PMC vetoes |
| Lazy majority | Majority of PMC “+1” votes |
| Lazy approval | Implicit allowance unless a “-1” PMC vote is received, at which time, depending on the type of action, either lazy majority or consensus approval must be obtained. |
| ⅔ majority | ⅔ of PMC “+1” votes |
| Unanimous consensus | All PMC “+1” votes |
A valid veto cannot be over-ruled, it can only be withdrawn by its issuer. Any veto must be accompanied by reasoning and be prepared to defend it. The validity of a veto, if challenged, can be confirmed by anyone who has a binding vote. This does not necessarily signify agreement with the veto - merely that the veto is valid. In case of disputes about whether a veto is valid, then opinion of the PMC chair is final. If you disagree with a valid veto, then you must engage the person casting the veto to further discuss the issues. The vetoer is obliged to vote early and to then work with the community to resolve the matter. If a veto is not withdrawn, the action that has been vetoed must be reversed in a timely manner.
This section describes the various actions which are undertaken within the project, the corresponding approval required for that action, and those who have binding votes over the action.
| Action | Description | Application | Binding votes |
|---|---|---|---|
| Code change | A change made to a codebase of the project by a committer. This includes source code, documentation, website content, etc. | Lazy approval | PMC |
| Release plan | Defines the timetable and actions for a release. A release plan cannot be vetoed (hence lazy majority). | Lazy majority | PMC |
| Product release | When a release of one of the project's products is ready, a vote is required to accept the release as an official release of the project. A release cannot be vetoed (hence lazy majority). | Lazy majority | PMC |
| Adoption of new codebase | When the codebase for an existing, released product is to be replaced with an alternative codebase. | ⅔ majority | PMC |
| Creation of new sub-project | When a new sub-project within an existing code base is to be created | ⅔ majority | PMC |
| New committer | When a new committer is proposed for the project. | Consensus approval | PMC |
| New PMC member | When a new member is proposed for the PMC. | Consensus approval | PMC |
| Select PMC chair | When a new PMC chair is required | Consensus approval | PMC |
| Reinstate emeritus member | An emeritus PMC member can be reinstated. | Consensus approval | PMC (excl member in question) |
| Committer removal | When removal of commit privileges is sought. | Unanimous consent | PMC (excl member in question, if applicable) |
| PMC member removal | When removal of a PMC member is sought. | Unanimous consent | PMC (excl member in question) |
| Determine whether another vote should be in confidence | When decisions necessitate privacy | Consensus approval | PMC (excl member in question, if applicable) |
Votes are normally open for a period of one to two weeks to allow all active voters time to consider the vote. If the vote has not achieved a quorum (the PMC chair decides if sufficient people have voted), then it can be extended for up to one additional month. If still no quorum, then the vote fails, and would need to be raised again later. Votes relating to code changes are not subject to a strict timetable, but should be made as timely as possible.
Discussion about the topic would have already happened in a [Proposal] thread to express the issues and opinions. The [Vote] thread is to ratify the proposal if that is felt to be necessary. The instigator shares the Vote proposal with the PMC. Describe the issue with no ambiguity and in a positive sense. Define the date and time for the end of the vote period. Votes are expressed using the voting symbols defined above. Voters can change their vote during the timeframe. At the end of the vote period, the instigator tallies the number of final votes and reports the results.
For breakdown situations and those requiring unanimous consensus, if this consensus cannot be reached within the extended timeframe, then the PMC Chair will make the ultimate decision.
The primary mechanism for communication is the project’s GitHub site. Anyone can participate, no matter what their time zone. A reliable searchable archive of past discussion is built. Oversight is enabled. Many eyes ensures that the project evolves in a consistent direction. Other communication channels may also be used, if only for a specific purpose and not permanently available. This policy ensures that solutions are available in the mailing list archives and enables people to respond at whatever time that they choose.
Private discussions are discouraged.
This section of the governance document provides the overarching philosophy of coding in the ActivitySim project. This document is not intended to be a technical guide for coding standard or technique. The ActivitySim development documentation covers the specific details of the contributing to the ActivitySim project.
ActivitySim is implemented in Python, and makes heavy use of the vectorized backend C/C++ libraries in pandas and numpy. The core design principle of the system is vectorization of for loops, and this principle is woven into the system wherever reasonable. As a result, the Python portions of the software can be thought of as more of an orchestrator, data processor, etc. that integrates a series of C/C++ vectorized data table and matrix operations.
The code base is designed to be regional or geography agnostic until implemented through configuration files. The mechanics of individual model components will be the same in each deployment which may result in certain workflow dependencies. This is by design, so that each region that adopts ActivitySim will benefit from improvements made in other regions with minimal effort.
The ActivitySim project adheres to strict style guidelines. This adherence ensures a tidy code base that is readable and usable by the largest audience possible. These guidelines and their strict enforcement also reduces potential coding errors due to convoluted or uncommon coding styles. The ActivitySim style guidelines are covered in the ActivitySim development documentation.
ActivitySim uses the GitHub Flow methodology for working together in the code repository. All contributions to the GitHub regardless of contributor shall follow the GitHub Flow methodology. Code contributions will not be accepted by the PMC until they have been reviewed entirely by someone other than the contributor, have sufficient and robust test coverage, and pass all tests. These rules ensures a well-tested and (hopefully) error-free code base. The goal of code reviews is not to chastise the contributor or inflate the ego of the reviewer.
The responsibility for fixing errors or bugs identified in the code review is the responsibility of the contributing author. It is not the responsibility of the code reviewer.
Code review is a great opportunity for new developers to learn the code base while contributing immediately to the overall project. Code review is also a great way to win the hearts and minds of the PMC and other developers on the project.
A complete description of the ActivitySim Code Review and Contribution are covered in the ActivitySim Development Documentation.
Licensing conditions from contributors that go beyond the terms of the ActivitySim license may not be introduced.If such issues do arise,they must be addressed it before the next release. The ActivitySim license is here.
The PMC will conduct continuous testing of the ActivitySim software to ensure contributions do not break existing functionality, new code is well formatted and functioning, and ensure consistency with prior versions of the software.
Before any deployment or code merge, the ActivitySim code must pass all tests. Any failing tests are the responsibility of the contributor to address before the pull request is deployed and merged.
The PMC will also establish unit test coverage goals and enforce a minimum threshold of test coverage of each new pull request.
A complete description of the ActivitySim Code Testing framework are covered in the ActivitySim Development Documentation.
All contributions must include complete documentation. If any of the documentation components are missing or deemed insufficient, the PMC will not accept the pull request. Each documentation component is intended to ensure that contributions are well understood by the community of developers, reviewers, and users.
A complete description of the ActivitySim documentation guidelines are covered in the ActivitySim Development Documentation.
Each contributor should be recognised and feel a productive part of the community, and it is a goal to encourage diversity, respect, and equality. Key to this is the recognition of contributions from individuals in a manner that also recognises the community effort that made it all possible. Contributions of actual code are supported by design discussion, oversight, testing, documentation, bug fixes and much more. No code contribution is an independent unit of work (or should not be). It is therefore impossible to credit individual contributors.
However, the following methods may be used to provide recognition:
-
All developers encourage other developers to participate, treat each other with respect, and openly collaborate. This enables the contributors to feel a part of the project and shows that their discussion and ideas are valuable. These discussions enhance the presence of their name in the project resource archives.
-
Encourage contributors to add patches via the issue tracker. This enables clear tracking of the issue and by default specifically shows who was the contributor.
-
When committers apply the patch, they refer to the issue number and the contributor's name. This enables linkage between the issue tracker and the repository history. It adds the contributor's name to the archives.
-
Committers apply patches as soon as possible. This keeps the contributor enthused and shows them that their work is valuable.
-
Committers add an entry for each significant contribution to the top-level changes document. This enables linkage to the relevant issue and shows the contributor's name. It also shows the initials of the committer who did the work to add the patch.
-
When committers are adding their own work, they similarly add entries to the "changes" documents. Their names are added to the entry.
-
The existing PMC will notice new contributors who are committed. It eventually invites them to become new committers/PMC members. See the notes about this topic.
-
Committers/PMC members are listed.
There is no specific documentation which lists each contributor and their work.