This repository has been archived by the owner on Aug 13, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updating root contributing file to match docs
- Loading branch information
1 parent
d48fcc2
commit 0e950ed
Showing
2 changed files
with
127 additions
and
35 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,47 +1,144 @@ | ||
| # Contributing to OpenAssistants | ||
| --- | ||
| sidebar_position: 6 | ||
| --- | ||
|
|
||
| Thank you for considering contributing to OpenAssistants! We value the contributions from our community, whether it's in the form of code, documentation, bug reports, feature requests, or any other form of participation. | ||
| # Contributing to openassistants | ||
| Welcome to the openassistants contributing page. Please follow the guidelines below when making contributions to the project. All effort is greatly appreciated! | ||
|
|
||
| ## Getting Started | ||
| ## Table of Contents | ||
| - [Bug Reports and Enhancement Requests](#bug-reports-and-enhancement-requests) | ||
| - [Finding an Issue to Contribute to](#finding-an-issue-to-contribute-to) | ||
| - [Submitting a Pull Request](#submitting-a-pull-request) | ||
| - [Version Control, Git, and GitHub](#version-control-git-and-github) | ||
| - [Getting Started with Git](#getting-started-with-git) | ||
| - [Creating a Fork of openassistants](#creating-a-fork-of-openassistants) | ||
| - [Creating a Feature Branch](#creating-a-feature-branch) | ||
| - [Making Code Changes](#making-code-changes) | ||
| - [Pushing Your Changes](#pushing-your-changes) | ||
| - [Making a Pull Request](#making-a-pull-request) | ||
| - [Updating Your Pull Request](#updating-your-pull-request) | ||
| - [Updating the Development Environment](#updating-the-development-environment) | ||
| - [Tips for a Successful Pull Request](#tips-for-a-successful-pull-request) | ||
|
|
||
| - Make sure you have a [GitHub account](https://github.com/signup/free). | ||
| - Submit an issue for your work, assuming one does not already exist. | ||
| - Fork the repository on GitHub. | ||
| - We recommend using [Poetry](https://python-poetry.org/) for managing the Python package dependencies and virtual environments. | ||
| ## [Bug Reports and Enhancement Requests](#bug-reports-and-enhancement-requests) | ||
|
|
||
| ## Making Changes | ||
| - **Search Existing Issues**: Before submitting a bug report, ensure it has not already been reported by searching existing issues. | ||
| - **Create New Issue**: If no issues address the bug discovered, [create a new issue](#https://github.com/definitive-io/openassistants/issues/new) | ||
| - **Describe the Bug**: Provide a clear description of the bug, including steps to reproduce, and what the expected outcome should be. | ||
| - **Include Details**: Specify the version of openassistants you're using, your operating system, and any relevant environment setup details. | ||
|
|
||
| ### Python Packages | ||
| ### Enhancement Requests | ||
| - **Propose New Features**: Clearly articulate your suggestions for new features or improvements, explaining how they would benefit the project. | ||
| - **Provide Rationale**: Offer reasons why this enhancement would be valuable to the project. | ||
|
|
||
| - Ensure you have a Python development environment set up, preferably with Poetry. | ||
| - Follow the Python style guide (PEP 8) for writing clean, readable code. | ||
| - Write tests for your new features or fixes and make sure existing tests pass. | ||
| - Document any changes in behavior or the API. | ||
| ### Reporting Process | ||
| - **Use Clear Titles**: When creating an issue, use a descriptive and clear title. | ||
| - **Submit on GitHub**: Report bugs and enhancements via the project's GitHub issues page. Tag your issue appropriately, whether as a bug or an enhancement. | ||
|
|
||
| ### TypeScript Packages | ||
|
|
||
| - Ensure you have a Node.js development environment set up. | ||
| - Follow the TypeScript style guide and best practices. | ||
| - Include unit tests with your changes and ensure all tests are passing. | ||
| - Update the documentation to reflect any changes or additions to the API. | ||
| ## [Finding an Issue to Contribute to](#finding-an-issue-to-contribute-to) | ||
|
|
||
| ## Submitting Changes | ||
| - **Explore the Issue Tracker**: Browse the GitHub issue tracker to find issues that interest you. Look for tags to find [issues](#https://github.com/definitive-io/openassistants/issues) you can contribute towards in your area of interest. | ||
| - **Understand the Issue**: Before picking an issue, ensure you understand the requirements and ask for clarification if needed. | ||
| - **Comment on the Issue**: Once you decide on an issue, comment on it, expressing your intention to work on it. This helps avoid multiple people working on the same issue. | ||
| - **Seek Guidance**: If you're new or unsure, don't hesitate to ask maintainers or the community for help or guidance. | ||
|
|
||
| - Push your changes to a branch in your fork of the repository. | ||
| - Submit a pull request to the main repository. | ||
| - Include a clear description of the changes and any relevant issue numbers. | ||
| - Wait for a maintainer to review your pull request, make any necessary updates, and merge it. | ||
|
|
||
| ## Code Review | ||
| ## [Submitting a Pull Request](#submitting-a-pull-request) | ||
|
|
||
| Your pull request will be reviewed by the maintainers who may request some changes, improvements, or further testing before your changes are merged. | ||
| - **Create a Fork**: Start by forking the repository. | ||
| - **Create a Feature Branch**: Make a new branch for your changes. | ||
| - **Implement Changes**: Work on your feature or bugfix in your branch. | ||
| - **Commit Changes**: Make concise and meaningful commit messages. | ||
| - **Sync with Main Branch**: Regularly sync your branch with the main branch to stay updated. | ||
| - **Run Tests**: Ensure your changes pass all tests. | ||
| - **Create Pull Request**: Once ready, submit a pull request to the main repository. | ||
| - **Describe Your Changes**: In the pull request, clearly describe what you've done. | ||
| - **Respond to Feedback**: Be responsive to feedback from project maintainers. | ||
|
|
||
| ## Community | ||
|
|
||
| Stay connected with the community: | ||
| ### [Version Control, Git, and GitHub](#version-control-git-and-github) | ||
|
|
||
| - Join our [Discord server](https://discord.gg/Snd4Cry7wD). | ||
| - Follow the project on [GitHub](https://github.com/definitive-io/openassistants) and participate in discussions. | ||
| - **Understand Version Control**: Familiarize yourself with the basics of version control systems, particularly Git, which is crucial for managing changes in the project. | ||
| - **Learn Git Basics**: Gain proficiency in Git commands like `clone`, `branch`, `commit`, `push`, `pull`, and `merge`. | ||
| - **Use GitHub Effectively**: Learn how to navigate and use GitHub for managing your work, submitting pull requests, and [collaborating](#https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) with others. | ||
| - **Follow Best Practices**: Adopt best practices for version control like committing small changes, writing meaningful commit messages, and keeping branches focused and short-lived. | ||
|
|
||
| Thank you for your contributions to OpenAssistants! | ||
|
|
||
| ### [Getting Started with Git](#getting-started-with-git) | ||
|
|
||
| - **Install Git**: Download and install Git from [git-scm.com](https://git-scm.com/). | ||
| - **Configure Git**: Set up your user name and email using `git config`. | ||
| - **Initialize a Repository**: Use `git init` to start a new repository. | ||
| - **Clone a Repository**: Use `git clone [url]` to clone an existing repository. | ||
| - **Learn Basic Commands**: Familiarize yourself with basic commands like `git add`, `git commit`, `git status`, and `git push`. | ||
| - **Read Git Documentation**: For a comprehensive understanding, refer to the [Pro Git book](https://git-scm.com/book/en/v2), available online for free. | ||
|
|
||
|
|
||
| ### [Creating a Fork of openassistants](#creating-a-fork-of-openasisstants) | ||
|
|
||
| - **Navigate to the Repository**: Visit the [openassistants GitHub repository](https://github.com/definitive-io/openassistants). | ||
| - **Fork the Repository**: Click the "Fork" button located at the top-right of the repository page. This action will create a personal copy of the repository in your own GitHub account. [Creating a fork](#https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) | ||
| - **Clone Your Fork**: After forking, clone your fork to your local machine using `git clone [your-fork-url]`. | ||
| - **Set Upstream Remote**: Configure the original 'openassistants' repository as an upstream remote using `git remote add upstream https://github.com/definitive-io/openassistants.git`. | ||
|
|
||
|
|
||
| ### [Creating a Feature Branch](#creating-a-feature-branch) | ||
|
|
||
| - **Switch to the Base Branch**: Ensure you are on the main branch using `git checkout main`. | ||
| - **Pull Latest Changes**: Update the main branch with `git pull upstream main`. | ||
| - **Create a New Branch**: Create a new branch for your feature or bug fix using `git checkout -b your-branch-name`. | ||
| - **Keep Branches Focused**: Make sure your branch focuses on a single feature or bug fix for clarity and easier review. | ||
|
|
||
|
|
||
| ### [Making Code Changes](#making-code-changes) | ||
|
|
||
| - **Understand Codebase**: Familiarize yourself with the structure and style of the 'openassistants' codebase. | ||
| - **Write Clean Code**: Follow coding standards and guidelines for readability and maintainability. | ||
| - **Implement Changes**: Focus on making changes that address the issue or add the proposed feature. | ||
| - **Test Your Changes**: Ensure your code works as intended and does not introduce new issues. | ||
| - **Document Your Changes**: Add comments and documentation where necessary to explain your modifications. | ||
|
|
||
|
|
||
| ### [Pushing Your Changes](#pushing-your-changes) | ||
|
|
||
| - **Stage Your Changes**: Use `git add` to stage the changes you've made. | ||
| - **Commit**: Commit your changes with `git commit -m 'Your informative commit message'`. | ||
| - **Pull Latest Changes**: Before pushing, pull the latest changes from upstream with `git pull upstream main`. | ||
| - **Resolve Conflicts**: If there are any conflicts, resolve them before proceeding. | ||
| - **Push to Your Fork**: Push your changes to your fork with `git push origin your-branch-name`. | ||
|
|
||
|
|
||
| ### [Making a Pull Request](#making-a-pull-request) | ||
|
|
||
| - **Review Changes**: Before submitting a pull request, review your changes to ensure they address the issue appropriately. | ||
| - **Create Pull Request**: Go to your fork on GitHub and click the "New pull request" button. Choose your feature branch and the main repository's main branch as the base. | ||
| - **Provide Details**: In the pull request description, clearly explain your changes and link to the issue if applicable. | ||
| - **Wait for Review**: Once submitted, wait for the project maintainers to review your pull request. They may request changes. | ||
| - **Make Requested Changes**: If changes are requested, make them in your branch and push the updates. | ||
|
|
||
|
|
||
| ### [Updating Your Pull Request](#updating-your-pull-request) | ||
|
|
||
| - **Review Feedback**: Carefully read any feedback from the project maintainers. | ||
| - **Make Changes**: Implement the necessary changes in your local branch. | ||
| - **Commit and Push**: Commit these changes and push them to your branch on GitHub. | ||
| - **Inform Reviewers**: Once the updates are pushed, inform the reviewers, preferably with a comment on the pull request. | ||
| - **Stay Responsive**: Be prepared to make further adjustments based on additional feedback. | ||
|
|
||
|
|
||
| ### [Updating the Development Environment](#updating-the-development-environment) | ||
|
|
||
| - **Stay Updated**: Regularly pull the latest changes from the main repository to your local development environment. | ||
| - **Manage Dependencies**: Update any dependencies as per the project's requirements. | ||
| - **Test Locally**: Regularly run tests to ensure your environment reflects the project's current state. | ||
| - **Seek Help if Needed**: If you encounter issues while updating, don't hesitate to ask for assistance from the community or maintainers. | ||
|
|
||
|
|
||
| ## [Tips for a Successful Pull Request](#tips-for-a-successful-pull-request) | ||
|
|
||
| - **Follow Project Guidelines**: Adhere to the coding style and contribution guidelines of the project. | ||
| - **Keep Changes Focused**: Ensure your pull request addresses a single issue or feature. | ||
| - **Write Clear Descriptions**: Clearly describe the purpose of your changes and how they impact the project. | ||
| - **Include Tests**: Add tests that validate your changes, if applicable. | ||
| - **Be Patient and Responsive**: Be patient for reviews and responsive to feedback and questions. |
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