Arranger Dev Documentation Update #892
+794
−8,509
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 |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| # Contributing to Overture | ||
|
|
||
| We appreciate your interest in contributing to this project. We are the Genome Informatics Software Engineering team from Ontario Institute for Cancer Research. At OICR we develop new software, databases and other necessary components to store, organize and process the large and complex datasets being generated by our cancer research programs. Embodying OICR's values of collaboration and community, we are firm believers in open-source and open-science. As such we strongly believe in the collective power of expertise and shared resources. | ||
|
|
||
| ## Code of Conduct | ||
|
|
||
| By participating in this project, you are expected to abide by our [Code of Conduct](/community/code-of-conduct). Please take the time to read it carefully before contributing. | ||
|
|
||
| ## Get Involved | ||
|
|
||
| **Getting Started:** Our primary platform for community support, feature requests, and general discussions is GitHub Discussions. This allows us to keep all conversations in one place and make them easily searchable for future reference. | ||
|
|
||
|
|
||
| **Community Support:** Our primary platform for community support, feature requests, and general discussions is [GitHub Discussions](https://github.com/overture-stack/docs/discussions). This allows us to keep all conversations in one place and make them easily searchable for future reference. | ||
|
|
||
| - **Getting Help:** If you need assistance with Overture, please create a [new discussion in our support category](https://github.com/overture-stack/docs/discussions/categories/support). | ||
| - Before creating a new discussion, please search existing discussions to see if your question has already been answered. | ||
| - **Feature Requests & Proposals:** We love hearing your ideas for improving Overture! Before making a feature request, please check our [**feature roadmap**](https://github.com/orgs/overture-stack/projects/11/views/1) to see if your idea is already planned. | ||
| - If your idea isn't on the roadmap, feel free to [**submit a feature request**](https://github.com/overture-stack/docs/discussions/categories/ideas) by creating a new discussion in our Ideas category | ||
| - **Report a Potential Bug:** We use GitHub Issues primarily for tracking confirmed bugs and ticketing development tasks. If you come across a potential bug or issue, please first post it to our [**GitHub support discussion forum**](https://github.com/overture-stack/docs/discussions/categories/support). | ||
| - This allows us to confirm the issue and gather more information if needed. If we determine that further development is required, we will create and tag you into a GitHub Issue from your discussion post. | ||
|
|
||
| ## Our Development Process | ||
|
|
||
| We use GitHub issues and pull requests for communication related to code changes. | ||
|
|
||
| ### Branch Organization | ||
|
|
||
| We use the following standard branches: | ||
|
|
||
| - `main` is for stable production code | ||
| - `develop` is the integration branch for new features | ||
| - `feature/<name>` for feature branches | ||
| - `release/v<version>` for release branches | ||
| - `hotfix/<name>` for hotfix branches | ||
|
|
||
| ## Pull Requests | ||
|
|
||
| ### Submitting a Pull Request | ||
|
|
||
| We welcome and encourage pull requests from the community. To submit a pull request, please follow these steps: | ||
|
|
||
| 1. **Fork the Repository**: Fork the Overture repository on GitHub. | ||
| 2. **Clone Your Fork**: Clone your forked repository to your local machine. | ||
| 3. **Create a New Branch**: Create a new branch for your changes. Use lowercase and hyphens (e.g., `feature/user-authentication`). Include ticket/issue numbers when applicable (e.g., `feature/PROJ-123-user-authentication`). | ||
| 4. **Make Your Changes**: Implement your changes and commit them to your branch. Write clear, concise commit messages in present tense (e.g., "Add feature" not "Added feature"). Reference issue numbers in commits when applicable. | ||
| 5. **Push Your Changes**: Push your changes to your forked repository. | ||
| 6. **Submit a Pull Request**: Open a pull request against the main repository. | ||
|
|
||
| ### Best Practices | ||
|
|
||
| 1. **Keep PRs as small as possible:** Focus on one feature or bug fix per pull request. Break large changes into smaller, more manageable pieces making it easier for reviewers to understand and approve your changes. | ||
|
|
||
| 2. **Use descriptive titles:** Start with a verb (e.g., "Add", "Fix", "Update", "Refactor"), briefly summarize the main purpose of the PR and include the issue number if applicable (e.g., "Fix user authentication bug (#123)"). | ||
|
|
||
| 3. **Describe how you tested it:** Explain the testing process you followed and mention any new automated tests you've added. | ||
|
|
||
| 4. **Provide a clear description:** Explain the purpose of your changes and list the main modifications you've made. Mention any potential side effects or areas that might need extra attention. | ||
|
|
||
| 5. **Link related issues:** Reference any related issues or pull requests. Use GitHub keywords to automatically link issues (e.g., "Closes #123", "Fixes #456"). | ||
| 6. **Keep the PR's branch up-to-date:** Regularly rebase your branch on the latest main branch and resolve any merge conflicts promptly. | ||
|
|
||
| 7. **Respond to feedback:** Be open to suggestions and willing to make changes. Address all comments from reviewers. If you disagree with a suggestion, explain your reasoning politely. | ||
|
|
||
| 8. **Include documentation updates:** If your changes affect user-facing features, update or create and issue detailing the relevant changes need to the documentation. Where appropriate include inline comments for complex code sections. | ||
|
|
||
| 10. **Be patient:** Reviewers will likely be unable to respond immediately. However, feel free to follow up politely if you haven't received feedback after a reasonable time. | ||
|
|
||
| ### Using Draft Pull Requests | ||
|
|
||
| Draft Pull Requests are an excellent way to document work in progress and facilitate early feedback. Use them to: | ||
|
|
||
| - Organize your thoughts and process | ||
| - Share early work and ideas with the team | ||
| - Get feedback on implementation approaches before finalizing code | ||
| - Track progress on long-running features | ||
|
|
||
| Guidelines for Draft Pull Requests: | ||
|
|
||
| 1. **Creation**: | ||
| - Open a pull request and select "Create draft pull request" | ||
| - Clearly mark the title with [WIP] or [DRAFT] prefix | ||
MitchellShiell marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 2. **Description**: | ||
| - Outline the current state of the work | ||
| - List planned tasks or improvements | ||
| - Highlight areas where feedback is specifically needed | ||
| 3. **Updates**: | ||
| - Regularly update the description or provide comments following commits with progress notes | ||
| - Use task lists (using `- [ ]` in Markdown) to track completion of sub-tasks | ||
| 4. **Collaboration**: | ||
| - Encourage early feedback and discussion | ||
| - Use the pull request comments for design discussions | ||
| 5. **Finalization**: | ||
| - Complete all planned work and address feedback | ||
| - Update tests and documentation | ||
| - Click "Ready for review" to move out of draft state | ||
|
|
||
| ### Merging a Pull Request | ||
|
|
||
| - Ensure all CI checks pass | ||
| - Obtain the required number of approvals | ||
| - Use the project's specified merge strategy (Typically squash and merge) | ||
| - Delete the source branch after merging if no longer needed | ||
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,99 +1,85 @@ | ||
| # Arranger | ||
|
|
||
| Arranger is a versatile, data-agnostic GraphQL search API that leverages Elasticsearch, designed to simplify the process of creating powerful search interfaces for complex datasets. It's accompanied by its own React component library to generate interactive and highly configurable search UIs. | ||
|
|
||
| </br> | ||
|
|
||
| > | ||
| > <div> | ||
| > <img align="left" src="ov-logo.png" height="50"/> | ||
| > </div> | ||
| > | ||
| > *Arranger is part of [Overture](https://www.overture.bio/), a collection of open-source software microservices used to create platforms for researchers to organize and share genomics data.* | ||
| > | ||
| > | ||
|
|
||
|
|
||
| ## Repository Structure | ||
|
|
||
| The repository is organized with the following directory structure: | ||
|
|
||
| ``` | ||
| arranger/ | ||
| ├── docker/ | ||
| │ ├── elasticsearch/ | ||
| │ ├── server/ | ||
| │ ├── test/ | ||
| │ └── ui/ | ||
| ├── modules/ | ||
| │ ├── admin-ui/ | ||
| │ ├── components/ | ||
| │ └── server/ | ||
| └── scripts/ | ||
| ``` | ||
|
|
||
| - **docker/**: Contains miscellaneous configuration files used for building Docker images of Arranger Server, and to support running a local developer environment. | ||
|
|
||
| - **docs/**: Markdown files that contain instructions on how to use Arranger and its capabilities, contribution guidelines, etc. | ||
|
|
||
| - **modules/**: Core Arranger modules: | ||
| - **admin-ui/**: (Inactive) Administration interface for generating and managing Arranger configuration files. | ||
| - **components/**: React components to streamline integration of search portals with an Arranger server. | ||
| - **server/**: The "Arranger" server itself, a GraphQL service that facilitates usage of Lucene-based search engines (e.g. Elasticsearch). | ||
| - **scripts/**: Utility scripts for development, deployment, and system management. | ||
|
|
||
| ## Documentation | ||
|
|
||
| Technical resources for those working with or contributing to the project are available from our official documentation site, the following content can also be read and updated within the `/docs` folder of this repository. | ||
|
|
||
| - **[Arranger Overview](https://main--overturedev.netlify.app/docs/core-software/Arranger/overview)** | ||
| - [**Setting up the Development Enviornment**](https://main--overturedev.netlify.app/docs/core-software/Arranger/setup) | ||
| - [**Common Usage Docs**](https://main--overturedev.netlify.app/docs/core-software/Arranger/setup) | ||
MitchellShiell marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Development Environment | ||
|
|
||
| - [Node.js](https://nodejs.org/) (v18 or higher) | ||
|
There was a problem hiding this comment. eek. this needs to be updated 😳 |
||
| - [npm](https://www.npmjs.com/) (v8.3.0 or higher) | ||
| - [Docker](https://www.docker.com/) (v4.32.0 or higher) | ||
|
|
||
| ## Support & Contributions | ||
|
|
||
| - For support, feature requests, and bug reports, please see our [Support Guide](https://main--overturedev.netlify.app/community/support). | ||
|
|
||
| - For detailed information on how to contribute to this project, please see our [Contributing Guide](https://main--overturedev.netlify.app/docs/contribution). | ||
|
|
||
| ## Related Software | ||
|
|
||
| The Overture Platform includes the following Overture Components: | ||
|
|
||
| </br> | ||
|
|
||
| |Software|Description| | ||
| |---|---| | ||
| |[Score](https://github.com/overture-stack/score/)| Transfer data to and from any cloud-based storage system | | ||
| |[Song](https://github.com/overture-stack/song/)| Catalogue and manage metadata associated to file data spread across cloud storage systems | | ||
| |[Maestro](https://github.com/overture-stack/maestro/)| Organizing your distributed data into a centralized Elasticsearch index | | ||
| |[Arranger](https://github.com/overture-stack/arranger/)| A search API with reusable search UI components | | ||
| |[Stage](https://github.com/overture-stack/stage)| A React-based web portal scaffolding | | ||
| |[Lyric](https://github.com/overture-stack/lyric)| A model-agnostic, tabular data submission system | | ||
| |[Lectern](https://github.com/overture-stack/lectern)| Schema Manager, designed to validate, store, and manage collections of data dictionaries. | | ||
|
|
||
| If you'd like to get started using our platform [check out our quickstart guides](https://main--overturedev.netlify.app/guides/getting-started) | ||
|
|
||
| ## Funding Acknowledgement | ||
|
|
||
| Overture is supported by grant #U24CA253529 from the National Cancer Institute at the US National Institutes of Health, and additional funding from Genome Canada, the Canada Foundation for Innovation, the Canadian Institutes of Health Research, Canarie, and the Ontario Institute for Cancer Research. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
not a request for change, but a note to myself, as I'll need to update this soon once we move on from this branching system