Click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on GitHub. For more details on how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/).
+ +This is now your own unique copy of the Brainhack Jupyter Book. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code!
+ +Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork) with the upstream repository, otherwise, you can end up with lots of dreaded [merge conflicts](https://help.github.com/articles/syncing-a-fork).
+ +While you can edit files [directly on Github](https://help.github.com/articles/editing-files-in-your-repository), sometimes the changes you want to make will be complex and you will want to use a [text editor](https://en.wikipedia.org/wiki/Text_editor) that you have installed on your local machine/computer. (One great text editor is [vscode](https://code.visualstudio.com/)). +In order to work on the code locally, you must clone your forked repository.
```bash git clone git@github.com:YOURUSERNAME/brainhack_jupyter_book.git cd brainhack_book ``` -To keep up with the changes in the Brainhack Jupyter Book repository, add the [Brainhack Jupyter Book repository](https://help.github.com/articles/configuring-a-remote-for-a-fork) as a remote to your locally cloned repository. +To keep up with the changes in the Brainhack Jupyter Book repository, add the [Brainhack Jupyter Book repository](https://help.github.com/articles/configuring-a-remote-for-a-fork) as a remote to your locally cloned repository.
-The first time you try to sync your fork, you may have to set the upstream branch: +The first time you try to sync your fork, you may have to set the upstream branch:
+ ```bash git remote add upstream https://github.com/brainhack_jupyter_book/brainhack_jupyter_book.git git remote -v # Making sure the upstream repo is listed. ``` -Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork/) with the upstream repository. -For example, to update your main branch on your local cloned repository: +Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork/) with the upstream repository.
+For example, to update your main branch on your local cloned repository:
`git fetch upstream` `git checkout main` `git merge upstream/main` -### Synchronize your main branch with the upstream main branch: :arrows_counterclockwise: +You can then create a new branch to work on an issue. Using a new branch allows you to follow the standard GitHub workflow when making changes. This [guide](https://guides.github.com/introduction/flow/) provides a useful overview of this workflow. Please keep the name of your branch short and self-explanatory.
`git checkout -b MYBRANCH` -### Installing Dependencies in a virtual environment :arrow_up: +For the requirements please have a look at our [requirements.txt](https://github.com/brainhackorg/brainhack_jupyter_book/blob/main/requirements.txt)
-To use a virtual environment for building the book project, run the following -from within the root folder of the brainhack jupyter book directory: + +[Virtual environments](https://the-turing-way.netlify.app/reproducible-research/renv/renv-options.html) +are a great way of isolating project-related dependencies from your system-level Python installation.
+ +For more details on virtual environments using a tool like `venv` in Python see +[here](https://docs.python.org/3/tutorial/venv.html).
+ +You can also use Conda that acts both as a way to manage your environments and install packages. For more info about Conda, you can check this page of the +[The Turing Way project](https://the-turing-way.netlify.app/reproducible-research/renv/renv-package.html).
+ +To use a virtual environment for building the book project, run the following +from within the root folder of the brainhack jupyter book directory:
1. If you are using `venv`: -either use this +either use this + ```bash # This line creates a virtual environment called 'venv' -python3 -m venv venv +python3 -m venv venv # This line activates the virtual environment On macOS and Linux: -source venv/bin/activate +source venv/bin/activate # This line activates the virtual environment On Windows -source venv/bin/activate +source venv/bin/activate ``` or you can use the following with `virtualenv` @@ -162,7 +224,7 @@ In case you want to use a specific python interpreter, specify the path as virtualenv -p /usr/bin/python3.7 brainhack ``` -After you create your virtual environment using either way described above, then you can install the requirements for building the book by running +After you create your virtual environment using either way described above, then you can install the requirements for building the book by running `pip install -r requirements.txt` @@ -183,6 +245,8 @@ Once the virtual environment is activated, packages will be installed in that en **HEADS UP**: if you close the terminal or deactivate `venv`, make sure to re-activate the virtual environment with `source venv/bin/activate` before typing any code. +