-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
90c23ec
commit 6860d50
Showing
1 changed file
with
125 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,128 @@ | ||
| # aeon_docs | ||
|
|
||
| Project Aeon's online docs repo. Online docs at: | ||
| This repo contains the source for the currently WIP version of Project Aeon's online docs. | ||
|
|
||
| The docs are built via Sphinx, and hosted via GitHub Pages. `src/` is the Sphinx source directory, and `docs/` is the Sphinx and GitHub Pages build directory. The docs are available at: https://sainsburywellcomecentre.github.io/aeon_docs/ | ||
|
|
||
| All organizational details will eventually be available on the docs, but for now some useful info can be found in the sections below: | ||
|
|
||
| ## Project Aeon Organization Overview | ||
|
|
||
| ProjectAeon is a collaborative effort to perform behavioral neuroscience experiments where the behavior and neural activity of freely moving animals engaging in a complex task are continuously recorded. This project is contributed to by researchers and support staff at UCL's SWC, Neurogears, and Datajoint. | ||
|
|
||
| If you are interested in joining this project, please contact the [project maintainers](#Project-Maintainers). | ||
|
|
||
| ## Credentials | ||
|
|
||
| Below are the required sets of credentials for Project Aeon's members: | ||
|
|
||
| - Microsoft Teams: contact Jai Bhagat, Goncalo Lopes, or Dario Campagner | ||
| - SWC Github organization: contact SWC Helpdesk([email protected]) | ||
| - SWC Github 'aeon' project: contact Jai Bhagat or Goncalo Lopes | ||
| - SWC HPC: contact SWC Helpdesk | ||
| - 'aeon' HPC Linux group: contact SWC Helpdesk | ||
| - Datajoint database username: contact Thinh Nguyen ([email protected]) | ||
|
|
||
| To be granted these credentials, please send a single email to all contact parties requesting this access. | ||
|
|
||
| ## Repositories | ||
|
|
||
| You must be an SWC Github 'aeon' project member to view some of these repositories. | ||
|
|
||
| ### [aeon_mecha](https://github.com/SainsburyWellcomeCentre/aeon_mecha) | ||
|
|
||
|  | ||
| [](https://codecov.io/gh/SainsburyWellcomeCentre/aeon_mecha) | ||
|
|
||
| Project Aeon's main library for interfacing with acquired data. Contains Python modules for raw data file io, data querying, data processing, data qc, database ingestion, and building computational data pipelines. This is the main user repository. | ||
|
|
||
| *Note*: All experiment data is acquired and/or triggered and/or synced by [Harp devices](https://www.cf-hw.org/harp). Code in the 'aeon_acquisition' and 'aeon_mecha' repos makes use of the [Harp protocol](https://github.com/harp-tech/protocol) during data acquisition, raw data file writing, and raw data file reading. In the 'harp-tech/protocol' Github repo, you can find documentation on [Harp device operation and common registers](https://github.com/harp-tech/protocol/blob/master/Device%201.0%201.4%2020200901.pdf), the [Harp binary protocol](https://github.com/harp-tech/protocol/blob/master/Binary%20Protocol%201.0%201.1%2020180223.pdf), and [Harp clock synchronization](https://github.com/harp-tech/protocol/blob/master/Synchronization%20Clock%201.0%201.0%2020200712.pdf). | ||
|
|
||
| ### [aeon_experiments](https://github.com/SainsburyWellcomeCentre/aeon_experiments) | ||
|
|
||
| Contains experiment workflows written in the Bonsai visual programming language. | ||
|
|
||
| ### [aeon_acquisition](https://github.com/SainsburyWellcomeCentre/aeon_acquisition) | ||
|
|
||
| Contains the source code for the 'aeon_acquisition' Bonsai package, which is heavily used in workflows in 'aeon_experiments'. | ||
|
|
||
| ### [aeon_analysis](https://github.com/SainsburyWellcomeCentre/aeon_analysis) | ||
|
|
||
| Contains Python modules for analysis of Aeon experiment data. | ||
|
|
||
| ### [aeon_lineardrive](https://github.com/SainsburyWellcomeCentre/aeon_lineardrive) | ||
|
|
||
| Contains source code for actuating a linear drive motor used in Aeon experiments (designed primarily for moving electrophysiology cabling during freely-moving experiments). | ||
|
|
||
| ### [aeon_feeder](https://github.com/SainsburyWellcomeCentre/aeon_feeder) | ||
|
|
||
| Contains low-level source code for pellet delivery via feeders used in Aeon experiments. | ||
|
|
||
| ### [aeon_docs](https://github.com/SainsburyWellcomeCentre/aeon_docs) | ||
|
|
||
| Contains source code for the Aeon docs site, built via Sphinx. Built docs at: https://sainsburywellcomecentre.github.io/aeon_docs/ | ||
|
|
||
| ## Dev Practices | ||
|
|
||
| ### Software Development Life Cycle (SDLC) | ||
|
|
||
| Our SDLC roughly follows the [iterative model](https://www.tutorialspoint.com/sdlc/sdlc_iterative_model.htm). | ||
|
|
||
| ### Versioning | ||
|
|
||
| We version all the following, according to [SemVer](http://semver.org/) numbering: | ||
|
|
||
| - Experiments, by name, including full hardware specs (arena, I/O devices, | ||
| acquisition computer, etc.) | ||
| - Repositories, including code related to: | ||
| - Bonsai experiment workflows | ||
| - Quality Control protocols (for raw and preprocessed data) | ||
| - Data processing algorithms | ||
| - aeon-db Database | ||
| - aeon-db tables | ||
|
|
||
| ### Issue Tracking | ||
|
|
||
| We prioritize and track dev progress using Github Discussions and Github Issues in Github Projects. Issues and Discussions should ideally be created in the specific repository appropriate for the Issue/Discussion; all experiment and general Issues and Discussions should be created in 'aeon_experiments'. | ||
|
|
||
| ### Continuous Integration (CI) | ||
|
|
||
| We use Github Actions to run CI. We run unit tests on Github Virtual Machines on Windows, MacOS, and Ubuntu. We run integration tests on the SWC HPC. Workflows of the CI jobs we run can be found in each repo's respective `.github/workflows/` directory. | ||
|
|
||
| ### Contributing | ||
|
|
||
| Each repository roughly follows the [github flow](https://guides.github.com/introduction/flow/) (which is adapted from the more general | ||
| [gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)). | ||
|
|
||
| In brief, each of our repos has 'main' and 'prod' branches. Feature and bug fix branches are branched off of 'main', with Pull Requests sent back into 'main'. 'main' contains the full commit history of the project, up to the latest stable commit. Upon merges into 'main', a squash merge is performed into 'prod', such that 'prod' contains an abbreviated commit history of the project, with commits pertaining only to Pull Request merges. 'prod' thus serves as a "production" branch to allow for easier readability of project history and easier reversion of uncaught bug commits. At certain agreed upon timepoints we create "stable releases" (available in the "releases" section of the repository) which serve as a snapshot of the code at the time, version numbered according to [SemVer](http://semver.org/). | ||
|
|
||
| When contributing to any repository, the change to be made should first be discussed in a Github Discussion or a Github Issue. Thereafter, contributors should create a new branch (branched off of 'main') that contains the changes/additions they wish to make, and then create a pull request for merging this branch into 'main'. | ||
|
|
||
| All pull requests will be reviewed by the [project maintainers](#Project-Maintainers). Minimally, maintainers should follow the below steps when reviewing pull requests: | ||
|
|
||
| 1) Ensure new code adheres to the [style and documentation guidelines](#Style-and-Documentation-Guidelines), is covered by a test, and passes a build test. These can all be checked via CI. | ||
|
|
||
| 2) As necessary, ensure `changelog`, `readme`, config and doc files are updated. | ||
|
|
||
| 3) When a branch is ready to be merged back into 'main', always make sure to first pull 'main' locally, then rebase the feature branch onto 'main' (cleaning up any merge conflicts as necessary), before merging the PR. The squash merge into 'prod' can be handled via CI. E.g., see [here](https://github.com/SainsburyWellcomeCentre/aeon_mecha/tree/main/.github/workflows/squash_merge_to_prod.yml) | ||
|
|
||
| ### Style and Documentation Guidelines | ||
|
|
||
| Please see our [style and documentation guidelines](https://github.com/ProjectAeon/blog/blob/main/style_and_doc_guidelines.md). | ||
|
|
||
| We also believe in the [readme manifesto](http://thinkinghard.com/blog/TheREADMEManifesto.html), which says that `readme` files should provide at least a general description that covers _all_ of a project's files, and that one `readme` per subdirectory is generally good practice. | ||
|
|
||
| ### Code of Conduct | ||
|
|
||
| Please see our | ||
| [code of conduct](https://github.com/ProjectAeon/blog/blob/main/code_of_conduct.md). | ||
|
|
||
| ## Project Maintainers | ||
|
|
||
| Jai Bhagat ([email protected]) | ||
|
|
||
| Gonçalo Lopes ([email protected]) | ||
|
|
||
| Dario Campagner ([email protected]) | ||
|
|
||
|
|
||
| Built via Sphinx, hosted via GitHub Pages.. `src/` is the Sphinx source directory, and `docs/` is the Sphinx and GitHub Pages build directory. |