Description
I am outlining some key points mainly for the purpose of quality control and the efficiency of operations. Please comment missed points below, and I will update them back here. To make it as short as possible, you should use common sense to explain general items. Please forgive me that some common knowledge may have also been emphasized, as I think it would be helpful for newbie of open-source projects. This documentation will be linked to the README file for the JuliaQuantum organization, and will be transferred to a editable document under the Roadmap repo once it becomes stable in practice.
Basic Agreement for Participating JuliaQuantum Projects
To ensure the continuous and sustainable development of the JuliaQuantum organization, the following basic agreement and instructions have been composed upon the initiative and development of this organization. We assume you have carefully read and understood the following items when you participate JuliaQuantum projects or become a member of the organization.
I. Purpose statement of JuliaQuantum.
JuliaQuantum as an open-source and non-for-profit organization is formed to unite the efforts of the quantum community to build fundamental and comprehensive Julia libraries for quantum mechanics, quantum chemistry, quantum information & computing, quantum measurement, quantum control and other quantum-related scientific fields. All libraries built by JuliaQuantum will be open-source and accessible on various operating systems. Through the open-source community collaborations organized under JuliaQuantum, we expect to maximize the performance of our codes, maintain the consistency of various functions and packages, span to a broad spectrum of applications and reduce the number of packages you need for technical computing in related fields. Carrying over the appealing features of the Julia language, JuliaQuantum projects are expected to bring you a foundation to build up more advanced programs relatively easily and fast. Moreover, as people got well organized, it becomes an immediately reachable goal to forge a sustainable ecosystem to promote our packages through participating nodes around the world and their activities and events sponsored by various sources interested in our projects as a whole.
II. Licensing under JuliaQuantum.
All projects under the coordination of JuliaQuantum organization are open source projects, and should be used and distributed under the claimed open-source licenses approved by Open Source Initiative. The default license for the produced codes and documentations is the MIT license. Other open-source licenses and external libraries can be used and should be specified in the LICENSE document of JuliaQuantum projects or where it specifies for specific cases. Documentations or websites under open-source licenses should allow redistribution, translation and customization to better fit a wide spectrum of needs of readers without bringing in damages to the legal rights of the original authors.
All video records or other first-hand and derived products made by or granted by JuliaQuantum contributors associated to an event sponsored or organized by JuliaQuantum should be distributed under an open-source license as well. For example, a video recorded for a meetup organized under the name of JuliaQuantum can be released via YouTube channel yet need to use the Creative Commons License instead of the default Standard YouTube License to permit free-of-charge editing and redistribution through other channels. Other resources released under JuliaQuantum should also use open-source licenses if possible. The default MIT license is assumed if no license or copyright claims under a JuliaQuantum repository.
A license of a repository or published product can be changed with the written permission from all related contributors to whom it affects. If a notification of requesting a change of the license has been sent to the contributors through email (contributors' email addresses can be found from the log of git commits) for longer than one month without receiving all positive response, the change can still be made if no less than two third of the total contributors related agree the change and no denial heared from all the received responses. The request of changing licenses should be made as a pull request or issue from the beginning.
III. Contribute to JuliaQuantum projects.
As an open-source organization, JuliaQuantum is powered by constructive contributions in various ways including implementing functionality of software or participating activities outlined but not limited to the Roadmaps, testing/debugging existing packages under JuliaQuantum, filing/solving issues or participating discussions under JuliaQuantum repository forums, news groups and emailing lists, as well as direct source code contributions through the usual pull request approach or direct write access to the source code repositories. Some notes on contributing to open-source projects can be found in the Julia's documentation for the base project and standards where the contribution targets and projects should be replaced by JuliaQuantum counterparts which will be introduced in this document.
IV. Organize JuliaQuantum projects.
1. Main Point: Integrating JuliaQuantum projects as an organizational entity.
The JuliaQuantum organization is formed under a clear purpose, and is promoted by organizing constructive projects. These projects can be categorized into two types:
a. Building Julia packages or libraries as a direct coding output of the organization, and associated activities to promote the specific packages. This type of projects can be counted in the units of repositories or packages on GitHub under JuliaQuantum.
b. Organizing events or non-coding activities that can help build a sustainable ecosystem of the organization and its packages. These projects include bringing JuliaQuantum projects and Julia to potential new users through meetups and hangouts, establishing developers' or users' nodes and networks, supporting JuliaQuantum members to participate related conferences to introduce JuliaQuantum's works to a broader audience, funds raising, introducing academic support teams into the organization, helping collect resources for teaching and learning how to use Julia and JuliaQuantum packages and so on so forth.
Each type of JuliaQuantum projects is essentially open to and powered by the community in large, yet its impact strongly depends on how they are organized over the organization by its contributors--especially members of JuliaQuantum. While the second type of projects span into a broad range of cases strongly relying on the social dynamics of JuliaQuantum contributors and is as important as the first type, the following sections of this document mainly focus on the first type of projects and the core procedures and principles that worth JuliaQuantum contributors baring in mind in order to integrate all of JuliaQuantum projects as a harmonic entity and to produce high-quality open-source library products for the community.
2. Add new repositories.
a. A new repository can be added under the name of JuliaQuantum organization with the permission of the steering team (see JuliaQuantum member teams in later section) of the organization. It is strongly suggested to have a project proposal posted in the issue forum of the Roadmap repository as well as the JuliaQuantum.github.io issue forum to notify the audience from the community for a public review lasting at least a week (see the Special repo section). Once the permission is granted, the proposer will be entitled as an owner of the JuliaQuantum organization--if he/she does not have the ownership before--to create the new repository and to manage the associated project under the organization. The new repository can also be created by the steering team members without granting the ownership to the proposer if not necessary to grant an ownership to the proposer or for the sake of management.
b. It is also suggested to have a prototype repository created under a personal account introduced for code review while proposing the new repository or project. This is helpful for the community to judge the value of the project and to raise constructive discussions on how to continue and improve this project, eventually it affects whether the steering team will pass the permission to create the new repository under the organization through listening to what the community say about the proposed direction. If the new repository will be modified based on the repository proposed, a simple fork of the original repository is not allowed to generate the new repository under the organization. You can push new content to the new repository as a fresh new project. A fork will confuse people regarding the releasing channel which should be solely under the name of JuliaQuantum organization. With this said, a JuliaQuantum repository should not be a child or derived repository of any other repositories. Instead, you can create the empty GitHub repository first, and then add the address as a remote location of the source repository on your local machine followed by a forced push to the new GitHub repository. Technically, for the last two step, you can use commands
``` console
git remote add NewRemoteName http://github.com/JuliaQuantum/NewRepoName.git
git push NewRemoteName [branch]
```
After these operations above, the newly born repository is officially recognized as JuliaQuantum's repository with all its revision history preserved and will be maintained by the community of JuliaQuantum as long as the organization exists. By default, the proposer of the project will be the leader of the repository and enjoy all the benefits an owner of the repository and the organization has--including being promoted as a steering team member of JuliaQuantum to make decisions on where the organization heads to.
3. Collaborative, creative and social coding.
You may have noticed that collaborative creation and being social are the nature of how JuliaQuantum and many other open-source projects are organized. Productive tools and techniques like Travis CI, Trello, Pivotal Tracker, Hubot and branching are highly encouraged to use in coding through GitHub. You can easily find detailed introductions on these tools and techniques online, for example, the GitHub help page and this blog post. More importantly, beyond coding itself, there are many other social contents worth everyone to cherish and to appreciate the opportunity of working together. For example, through working on one project or participating discussions in the community, people become friends, build connections to each other and have meetups and even collaborate on researches and establish local nodes for projects. JuliaQuantum naturally supports those social activities and indeed is really powered through those activities. People interested in a project, especially contributors of a project, are encouraged to make tutorials, demos and to introduce the project to researchers and teachers to use them in real life and to teach other people to use it. While we respect everyone's purpose of working together under the constrain of social standards, we should be open to think deeper on how our activities in JuliaQuantum will shape a new world by opening up more opportunities or by other measures, what are important and how to improve, and examine our ideas in practice. The spirit in you could become the culture of JuliaQuantum in a long run.
4. Quality control.
JuliaQuantum projects should maintain a high quality of the integrity, usability, compatibility, consistency, readability and generality of implemented programs within the individual packages, across the scope of JuliaQuantum projects and beyond. To achieve a high quality standard, transparency of coding is the key--beyond the organization works as a union to bring back more people to review and participate our projects. Below are some general tips and standards that JuliaQuantum projects should follow:
a. _Tracking problems in issues_: Any problems found that may be caused by the loss of integrity, usability, compatibility, consistency and generality should be filed in the issue page of corresponding code repositories, and should be assigned to some JuliaQuantum members who could fix them--if possible, or be solved by volunteers before the release of the associated milestone version. Certainly, feature requests and other related issues can and should also be filed and tracked in the issue pages of JuliaQuantum repositories in a similar way.
b. _Documentations_: A consistent tool or format of documentation and profiling should be used within a repository. Clear descriptions of code lines should be commented in the source code when coding. Sphinx or JuliaDoc and other tools are encouraged to use for documenting JuliaQuantum projects. Starting from Julia 0.4.0, comments in source code should be compatible with the @doc and other Julia documentation macros. As a scientific organization, scientific references are required to be added in the comments wherever it is necessary. The documentation should be completed and up-to-date before an official version is released and registered as a Julia package.
c. _Tests and demos are necessary parts for implementing a new feature_: whenever a new functionality is implemented, unit tests and possibly some systematic tests and some demos should be included with the main code file. This is a requirement for a pull request to implement a new feature. Important features of a package should use pull requests to integrate to the releasing channel of the head repository.
d. _Traceable progress_: A JuliaQuantum coding project should define its scope and mark its progress in the Roadmap repository as time moves on. The scope of a repository can be first discussed as an issue post in the Roadmap repository, JuliaQuantum.github.io repository or its own home repository. As the scope becomes clear, the corresponding target items should be marked in the _LongTerm.md_ roadmap in the Roadmap repository and maybe also another short term roadmap documentation of the Roadmap repository defining the timeline of recently focused projects under the organization. As the scope changes or milestones have been reached, those long-term and short-term roadmaps should be updated accordingly. It is also required to have a clear announcement posted over the JuliaQuantum.github.io website and its repository when the package is officially released or updated to a new version after being registered as a Julia package. Certainly, posting important progress over social networks through JuliaQuantum public pages and connections is encouraged as well. All of this updating work should be mainly in charged by the leader(s) of the project or members in the projects who are also in the steering team. Audience should be able to follow those announcement channels to easily monitor the progress of JuliaQuantum projects.
5. Minimal effort principle for structuring library packages.
As JuliaQuantum is organized to build Julia Libraries--instead of isolated packages--for quantum science and technology, the main focus of our coding work is to present and implement in Julia the scientific concepts and algorithms. For maintenance and usage purpose, we do not want to make only one huge package to fit into all the wide spectrum of quantum science and technology. There is a strategy we should follow in JuliaQuantum to structure our packages and the connections among them, which we call the minimal effort principle as will be illustrated below.
a. _Statement of the level structure of JuliaQuantum packages_: Overall, there are three levels of Julia library packages we want to make in this organization according to their serving purpose and targeted field: fundamental representations of quantum types, fundamental solvers for basic quantum mechanical problems and advanced topics of quantum science and technology. These levels of packages should yield enough programming abstractness to combining different modules together for particular usage purpose while reducing the development and maintenance efforts to the minimal level. For instance, the QuBase.jl project belongs to the first level of JuliaQuantum libraries, which defines the typing system and representations of quantum states, operators, super-operators and so on. The basic quantum dynamics solvers to solve Schrodinger equations and Heisenberg equations should belong to the second level of libraries. Similarly, a package defines some common concepts of quantum information science could be categorized as a package on the third level. For a user who wants to calculate the entropy evolution of an open quantum system, he can merely import the quantum information package on the third level which has already imported the necessary typing system and solvers in the QuBase.jl package and some quantum dynamics solver packages by JuliaQuantum developers, to solve the state evolution of the system and then solve the entropy evolution using the quantum information package on his computer. Notice that entropy has been defined in different ways according to the applied fields, by importing the correct packages, the user can pick up the Shannon entropy, for example, in quantum information science without bothering to distinguish the definitions in another irrelevant quantum chemistry package. For developers, they can focus on particular aspects of the library system and optimize the algorithms in different levels without redefining common types and methods that have been already included in other packages.
b. _Combining packages if possible yet separating for development difficulties_: When a potentially new project is proposed, it is good to check if it can be absorbed into an existing package under developing on the same of level of coding purpose. The first two levels of libraries focus on general purpose computing tasks of quantum mechanics, and can be made as general as possible while interfaced to different scenarios of data structure benefited from the dispatching capability of Julia language. Notice that there can be many separated packages on the same level of category if the packages have completely different focuses and are hardly used at the same time. For instance, dynamics problems solvers and energy structure solvers can be separated into two packages. Different disciplines, like quantum chemistry and quantum information, should be separated into isolated packages to avoid conflicts and maintenance efforts even though there is a small section of overlap among them.
c. _Modular design_: All packages under JuliaQuantum should follow the modular design approach. The package should have a relatively clear target of usage scenarios, necessary exported types and functions, and can be used in arbitrary combinations with other published or home-made JuliaQuantum and Julia packages seamlessly. When the package needs to define a type or implement a function, it is required to reuse or import the existing modular if the type or function has been defined or implemented in another existing JuliaQuantum repository. General improvements should be made in the source packages if needed. Enough and minimal set of dependent modules should be imported to the package under development so that programming tasks on a higher level do not need to import too many packages from all the levels of JuliaQuantum libraries. Improvements can be made in the derived package over an existing JuliaQuantum type or function defined in another package if the improvements only help in some special scenarios that may not be useful for users of the source package.
5. Special repositories.
Beyond the three-level category of JuliaQuantum library packages/repositories discussed above, there are three special repositories shared by all JuliaQuantum projects and can be modified directly by all JuliaQuantum members. The special repositories as will be listed below will not registered as Julia packages yet are important to help glue all the other packages and projects together.
a. _JuliaQuantum.github.io_: This repository stores the source code of the public page for JuliaQuantum, and also holds discussions on general affairs of the JuliaQuantum organization through its issue page. Members of JuliaQuantum organization have write permission and maintenance responsibilities to announce progresses of JuliaQuantum projects to the community through our official website at http://JuliaQuantum.github.io and its issue forum. It is recommended to watch or star this repository to follow up the progresses and announcements of the organization.
b. _Roadmap_: This repository holds roadmaps and timelines of JuliaQuantum projects in terms of text files, as well as discussions on project proposals and general issues of the roadmaps on its issue page. It is recommended to people who are interested to participate peer-review of project proposals and organizational roadmap making to watch or star this repository in order to receive prompt notifications.
c. _Resources_: This repository stores some resources of JuliaQuantum meetup records, tutorials and educational materials of JuliaQuantum packages and so on.
6. Relationships to Non-JuliaQuantum organizations and projects.
JuliaQuantum as an umbrella organization supports all Julia organizations and projects to develop toward excellence in a large ecosystem. We encourage collaborations by our members with organizations and groups of people beyond JuliaQuantum as well. Packages not developed, released or maintained under the name of JuliaQuantum can be used as dependent packages yet should not be a major focus of development under the organization to diverge its limited developers' attentions.
7. Relationship to the Julia language organization (JuliaLang).
JuliaQuantum is an umbrella organization of JuliaLang started by the creators of the Julia language, and benefits from the broad network of JuliaLang as an open-source and a not-for-profit organization. Volunteers in the JuliaLang network work on providing conference opportunities, some financial support and other supports for JuliaQuantum and its contributors, and hence JuliaQuantum can focus on tasks related to quantum science and technology. Currently, JuliaQuantum does not collect funds from the public, and all donations should go to the fund raising channels of JuliaLang as an entity--for example, the channel at http://numfocus.org/projects/.
V. Release cycles of JuliaQuantum packages:
1. Plan and start.
Every new repository passed the proposal review or a repository starting moving on to a new version should have its scope, long-term and short-term roadmaps and milestones with an estimated timeline if possible to be posted and discussed in its own repository and summarized in the Roadmap repository as time moves on. Necessary information about leaderships, code structure, documentation and collaboration tools for the project should be confirmed along developing the package. Notice that, the nearest one- or two-cycling short-term or long-term milestones or roadmaps can only list some important subprojects within the repository and are used to focus the community's efforts on reachable and inevitable targets. Beyond stepping through the major milestones, other issues filed by the community should also be sorted out for proper release cycles and got solved in the mean time. Upon closing all related issues and the completing of the targets of a milestone, a new version of the library can be released and announced. The corresponding management job should be mainly done by the project leader(s) and JuliaQuantum members with the collective help from the community.
2. Tag version numbers.
For development and releasing purpose, packages should be tagged (using git tag command) with semantic version numbers formatted as _MAJOR.MINOR.PATCH_ or similar with a possible suffix of key words pre-release, ReleaseCandidate1 or rc1 and so on. The details of the increment of version numbers can be found here. Compatibility may be broken for early immature versions or when the first version series number is jumping. There can be one or multiple development branches opened for the community to work on various versions. Correspondingly, on the issue page of the repository, version numbers and milestones should be tagged clearly by the project leaders to sort out the workforce. Once a version is ready to release, this instruction should be followed on GitHub to tag a released version and to publish the package. If the package has already been published as an official Julia package, the package manager(s) can use Pkg.tag() followed by Pkg.publish command from Julia interface to tag and update the package automatically (see below).
3. Register as a Julia package.
Once the package under development has reached a relatively stable state, it should be registered and published as an official Julia package. You can search Pkg.register and Pkg.publish from the Julia manual for details. The basic idea is to write the URL of the repo to the Julia METADATA.jl file of the Julia base repo. After publishing the package, the version number of the package can be tagged by using Pkg.tag function in Julia and updated to the official Julia repo using Pkg.publish. For JuliaQuantum projects, it is not necessary and not suggested to register a new library to METADATA.jl at the beginning of building. A package of JuliaQuantum library should not be registered to Julia package manager until the basic functionality is implemented and well-documented and the design of the framework has been proved being reliable through sufficient tests and discussions. An owner or core member of a project or repository should file an issue for community review on the attempt of registering the package to the Julia package manager system for at least a week before the registration. Once a version is registered in Julia's METADATA.jl, in principle, later versions should maintain good consistency and compatibility with the registered version.
4. Update progress.
Whenever a new version of the package is updated after registering as an official Julia package, it is required to have a post displayed on the news page of the JuliaQuantum website. Related manuals of the package should also be updated with a brief log of the update before publishing. The long-term and short-term roadmaps in the Roadmap repo or the scope documents should be checked to see if the updates affect any items there. The major subprojects to be focused on, if any, for the next releasing cycle should be posted as an issue post or marked in the files of the Roadmap repo. For the case that multiple versions have been working on by the community in parallel, it is good to have milestone tags in the repo's issue forum.
5. Other notes.
If all the leaders of a JuliaQuantum project quite their leadership roles to maintain the package, the last leader has the responsibility to find proper people to continue the maintenance work. Otherwise, the steering team of the JuliaQuantum organization automatically takes the responsibility to help find people to continue the maintenance job.
VI. JuliaQuantum member teams.
Although JuliaQuantum is openly powered by the whole community and it does not require a JuliaQuantum contributor to be registered as a member of the JuliaQuantum organization, it is still necessary to establish a system of membership to maintain our source codes homed on GitHub and to represent our organization to participate community activities responsibly. Below are the major member teams of the JuliaQuantum organization--many of the teams refer to the organizational teams registered on GitHub. Among all JuliaQuantum teams, the steering team shown on the JuliaQuantum website has the ultimate right and responsibility to reorganize JuliaQuantum teams and assign permissions to JuliaQuantum members. All the other teams are mainly project-oriented and have limited rights and responsibilities when committing JuliaQuantum activities.
1. JuliaQuantum team.
All JuliaQuantum GitHub members are added into this team by default. Members in this team have write access to all the special repos on GitHub for their convenience of making prompt notifications of changes to the community. A JuliaQuantum member can only be invited by an owner of the organization to join the JuliaQuantum team due to their existing or potential significant contribution to the organization. A JuliaQuantum team member can be further added to one or more user teams under JuliaQuantum. A member of JuliaQuantum has the obligation to be assigned to solve issues of participating projects, if he/she is capable and willing to solve those issues. A JuliaQuantum team member can represent the organization to organize a project or activity under the name of JuliaQuantum in the case that a written permission has been granted by a steering team member of the organization. The membership of a person may be deprived in result of being removed from the JuliaQuantum team due to committing or merging codes which do not follow this basic agreement or violating the JuliaQuantum community spirits in the process of participating organizational projects or affairs. Legal responsibilities of violations against this basic agreement and laws should be solely taken by the JuliaQuantum members--if any at the moment when the violations happened--or other personals who have committed those violations. The organization as a loosely organized public community has no responsibilities to be assumed as a respondant to any violative behaviors. A JuliaQuantum team member can leave the team by himself at any time, of course.
2. Owners team.
An owner of any JuliaQuantum GitHub repository is also an owner of the JuliaQuantum organization and is in the Owners team on GitHub. An owner has the full access permissions to the organization's repositories and the management page while she/he should limit the usage of the administration power to where she/he was granted to by the steering team. An owner of JuliaQuantum, if not been invited to become a steering team member, should only has administration power over a project or a repo. Owners can invite a JuliaQuantum member to become a JuliaQuantum member of the organization if necessary for better participating a JuliaQuantum project, which should be carefully considered before committing. The ownership of the organization can be deprived upon public reports and proofs of violence of the organization's spirit and the basic agreements in their organizational behaviors. A JuliaQuantum owners team member can leave the team by himself at any time.
3. The steering team.
A steering team member is out of the owners team and has the ultimate obligation to maintain the smooth operation of the JuliaQuantum organization, and the ultimate responsibility of the quality control process of JuliaQuantum package development and organizational activities. The steering team member collectively manage the public email and social media accounts for the JuliaQuantum organization, can request official financial support from the Julia head node, and can authorize activities and projects under the name of the organization. Depending on the need, the steering team members should hold discussions on renewing the long-term and short-term roadmaps for the future projects of the organization. If necessary, administration activities should be noticed by the steering team members in the public domain through the JuliaQuantum communication channels, and decisions should be made by the steering team members after absorbing enough effective inputs from the community if possible.
4. Other teams or groups.
If needed, other JuliaQuantum teams can be formed for easing JuliaQuantum projects granted by an owner of the organization. Limited access and administration power (less than the owners team level) can be granted to the team members if and only if it does not hurt the normal development of the organization. Supporting groups and academic consultant committee or local package users teams that may not be associated with GitHub users can also be named and announced by the steering team or maybe members of the organization on the JuliaQuantum website to help the sustainable development of JuliaQuantum.
VII. Credit to contributors.
1. Cite JuliaQuantum works.
In formal publications, the use of JuliaQuantum packages should be acknowledged at least through citing the organization's website or the specific code repository page, and should follow the acknowledgement instruction (if any) associated with the cited JuliaQuantum projects. By citing JuliaQuantum works properly, credits of JuliaQuantum packages automatically pay to all contributors of the corresponding JuliaQuantum projects. The list of contributors to a JuliaQuantum package can be viewed on its GitHub repository pages--including code contributors, bug hunters, feature proposers and organization maintainers. Without the input of any single one of the contributors, we, as the whole community of JuliaQuantum, would not have the final version presented in the public domain.
2. Publish JuliaQuantum works.
JuliaQuantum organization encourages publications in all forms to introduce our works to a broader community. Owners and active contributors of the organization hold the ultimate rights of explanation of the associated development works of JuliaQuantum projects. One is suggested to consult with corresponding contributors before interpreting the works done in JuliaQuantum to the public.
VIII. Revision of this basic agreement.
This basic agreement is officially stored in the _JuliaQuantum.github.io_ repo, and is colletively maintained by the community. A change of this basic agreement document can be made through a pull request under a public review no shorter than one week. Disputes regarding any items of this document shall be raised in the issue forum of the JuliaQuantum.github.io repo or the pull request for revision. A new review cycle reset when all the disputes in a pull request of revision dissolved--if any--before changes can be made to the file. It automatically takes effect after the change has been merged by a JuliaQuantum member to the master branch without notifying the community in any other manners. Wrong operation of the revision process will result in an invalidity of changes made by the associated improper operation, and should be reclaimed as an open issue in the JuliaQuantum.github.io repo for no less than one week to make the last changes valid.