|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Changes |
| 4 | + |
| 5 | +The list of changes can be found in the [Changelog](https://github.com/ranaroussi/yfinance/blob/main/CHANGELOG.rst) |
| 6 | + |
| 7 | +## Running a branch |
| 8 | + |
| 9 | +### With PIP |
| 10 | + |
| 11 | +```bash |
| 12 | +pip install git+https://github.com/ranaroussi/yfinance.git@BRANCH |
| 13 | +``` |
| 14 | + |
| 15 | +E.g.: |
| 16 | + |
| 17 | +```bash |
| 18 | +pip install git+https://github.com/ranaroussi/yfinance.git@feature/something |
| 19 | +``` |
| 20 | + |
| 21 | +### With Git |
| 22 | + |
| 23 | +1: Download from GitHub: |
| 24 | + |
| 25 | +```bash |
| 26 | +git clone https://github.com/ranaroussi/yfinance.git |
| 27 | +``` |
| 28 | + |
| 29 | +Or if a specific branch: |
| 30 | + |
| 31 | +```bash |
| 32 | +git clone -b <BRANCH NAME> https://github.com/ranaroussi/yfinance.git |
| 33 | +``` |
| 34 | + |
| 35 | +> [!NOTE] |
| 36 | +> Only do the next part if you are installing globally |
| 37 | +> |
| 38 | +> If you are installing for 1 specific project, then you can skip this step |
| 39 | +> and just `git clone` in the project directory |
| 40 | +
|
| 41 | +2: Add download location to Python search path |
| 42 | + |
| 43 | +Two different ways, choose one: |
| 44 | + |
| 45 | +`. Add path to PYTHONPATH environment variable |
| 46 | +1. Add to top of Python file: |
| 47 | +```python |
| 48 | +import sys |
| 49 | +sys.path.insert(0, "path/to/downloaded/yfinance") |
| 50 | +``` |
| 51 | + |
| 52 | +3: Verify |
| 53 | + |
| 54 | +```python |
| 55 | +import yfinance |
| 56 | +print(yfinance) |
| 57 | +``` |
| 58 | + |
| 59 | +Output should be: |
| 60 | + |
| 61 | +`<module 'yfinance' from 'path/to/downloaded/yfinance/yfinance/__init__.py'>` |
| 62 | + |
| 63 | +If output looks like this then you did step 2 wrong |
| 64 | + |
| 65 | +`<module 'yfinance' from '.../lib/python3.10/site-packages/yfinance/__init__.py'>` |
| 66 | + |
| 67 | + |
| 68 | +## Branches |
| 69 | + |
| 70 | +To support rapid development without breaking stable versions, this project uses a two-layer branch model:  ([inspiration](https://miro.medium.com/max/700/1*2YagIpX6LuauC3ASpwHekg.png)) |
| 71 | + |
| 72 | +* **dev** : new features & some bug-fixes merged here, tested together, conflicts fixed, etc. Once stable, can merge to ... |
| 73 | + |
| 74 | +* **main**: stable branch. Where PIP releases are created |
| 75 | + |
| 76 | + |
| 77 | +Most of the time you want to target the **dev** branch, but default is **main** so remember to switch to **dev**. |
| 78 | + |
| 79 | +**Exception:** can straight merge into **main** if: |
| 80 | + |
| 81 | +* yfinance is massively broken |
| 82 | + |
| 83 | +* or part of yfinance is broken and the fix is simple and clearly doesn't affect anything else |
| 84 | + |
| 85 | +* or not editing part of the code (e.g. editing this file) |
| 86 | + |
| 87 | + |
| 88 | + |
| 89 | +### I'm a GitHub newbie, how do I contribute code? |
| 90 | + |
| 91 | +1. Fork this project. If already forked, remember to `Sync fork` |
| 92 | + |
| 93 | +2. Implement your change in your fork, ideally in a specific branch |
| 94 | + |
| 95 | +3. Create a Pull Request, from your fork to this project. If addressing an Issue, link to it |
| 96 | + |
| 97 | + |
| 98 | +### [How to download & run a GitHub version of yfinance](https://github.com/ranaroussi/yfinance/discussions/1080) |
| 99 | + |
| 100 | +## Documentation website |
| 101 | + |
| 102 | +The new docs website [ranaroussi.github.io/yfinance/index.html](https://ranaroussi.github.io/yfinance/index.html) is generated automatically from code. When you fetch a branch or PR, probably it also has changes to docs - to generate and view this: |
| 103 | + |
| 104 | +```bash |
| 105 | +pip install -r requirements.txt |
| 106 | +pip install Sphinx==8.0.2 pydata-sphinx-theme==0.15.4 Jinja2==3.1.4 sphinx-copybutton==0.5.2 |
| 107 | +sphinx-build -b html doc/source doc/_build/html |
| 108 | +python -m http.server -d ./doc/_build/html |
| 109 | +# open "localhost:8000" in browser |
| 110 | +``` |
| 111 | + |
| 112 | +## Unit tests |
| 113 | + |
| 114 | +Tests have been written using the built-in Python module `unittest`. Examples: |
| 115 | + |
| 116 | +* Run all price tests: `python -m unittest tests.test_prices` |
| 117 | + |
| 118 | +* Run sub-set of price tests: `python -m unittest tests.test_prices.TestPriceRepair` |
| 119 | + |
| 120 | +* Run a specific test: `python -m unittest tests.test_prices.TestPriceRepair.test_ticker_missing` |
| 121 | + |
| 122 | +* Run all tests: `python -m unittest discover -s tests` |
| 123 | + |
| 124 | +> [!NOTE] |
| 125 | +> The tests are currently failing already |
| 126 | +> |
| 127 | +> Standard result: |
| 128 | +> |
| 129 | +> **Failures:** 11 |
| 130 | +> |
| 131 | +> **Errors:** 93 |
| 132 | +> |
| 133 | +> **Skipped:** 1 |
| 134 | +
|
| 135 | +## Git stuff |
| 136 | +### commits |
| 137 | + |
| 138 | +To keep the Git commit history and [network graph](https://github.com/ranaroussi/yfinance/network) compact please follow these two rules: |
| 139 | + |
| 140 | +* For long commit messages use this: `git commit -m "short sentence summary" -m "full commit message"` |
| 141 | + |
| 142 | +* `squash` tiny/negligible commits back with meaningful commits, or to combine successive related commits. [Guide](https://docs.gitlab.com/ee/topics/git/git_rebase.html#interactive-rebase) but basically it's: |
| 143 | + |
| 144 | + |
| 145 | +```bash |
| 146 | +git rebase -i HEAD~2 |
| 147 | +git push --force-with-lease origin <branch-name> |
| 148 | +``` |
| 149 | + |
| 150 | +### rebase |
| 151 | + |
| 152 | +You might be asked to move your branch from `main` to `dev`. Make sure you have pulled **all** relevant branches then run: |
| 153 | + |
| 154 | +```bash |
| 155 | +git checkout <your branch> |
| 156 | +git rebase --onto dev main <branch-name> |
| 157 | +git push --force-with-lease origin <branch-name> |
| 158 | +``` |
0 commit comments