Skip to content

Commit ac13a72

Browse files
spjuhelspjuhel
committed
Addresses env setup for develop/review
1 parent d7cae4f commit ac13a72

File tree

3 files changed

+109
-41
lines changed

3 files changed

+109
-41
lines changed

‎doc/development/Guide_CLIMADA_Development.ipynb‎

Lines changed: 70 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,74 @@
6969
"\n"
7070
]
7171
},
72+
{
73+
"cell_type": "markdown",
74+
"metadata": {},
75+
"source": [
76+
"To develop (or review a pull request), you need to setup a proper climada development environment. This is relatively easy but requires rigor, so please read all the instructions below and make sure to follow them (we also recommend to read everything once first, and then follow them from the start). \n",
77+
"\n",
78+
"First, follow the [Advanced instructions](../getting-started/install.rst#install-advanced). Note that if you want to work on a specific branch instead of `develop`, if you work on a feature for instance), you need to checkout that specific branc instead of `develop` after cloning:\n",
79+
"\n",
80+
"```\n",
81+
"git clone https://github.com/CLIMADA-project/climada_python.git\n",
82+
"cd climada_python\n",
83+
"git checkout <other branch>\n",
84+
"```"
85+
]
86+
},
87+
{
88+
"cell_type": "markdown",
89+
"metadata": {},
90+
"source": [
91+
"### Note on dependencies\n",
92+
"\n",
93+
"Climada dependencies are handled with the `requirements/env_climada.yml` file.\n",
94+
"When you run `mamba env update -n <your_env> -f requirements/env_climada.yml`, the content of that file is used to install the dependencies, thus, if you are working on a branch that changes the dependencies, make sure to be on that branch **before** running the command."
95+
]
96+
},
97+
{
98+
"cell_type": "markdown",
99+
"metadata": {},
100+
"source": [
101+
"## Working on feature branches\n",
102+
"\n",
103+
"When developing a big new feature, consider creating a feature branch and merging smaller branches into that feature branch with pull requests, keeping the whole process separate from `develop` until it's completed. This makes step-by-step code review nice and easy, and makes the final merge more easily tracked in the history.\n",
104+
"\n",
105+
"e.g. developing the big `feature/meteorite` module you might write `feature/meteorite-hazard` and merge it in, then `feature/meteorite-impact`, then `feature/meteorite-stochastic-events` etc... before finally merging `feature/meteorite` into `develop`. Each of these could be a reviewable pull request.\n",
106+
"\n",
107+
"### Make a new **branch**\n",
108+
"\n",
109+
"For new features in Git flow:\n",
110+
"\n",
111+
" git flow feature start feature_name\n",
112+
" \n",
113+
"Which is equivalent to (in vanilla git):\n",
114+
"\n",
115+
" git checkout -b feature/feature_name\n",
116+
"\n",
117+
"Or work on an existing branch:\n",
118+
"\n",
119+
" git checkout -b branch_name\n",
120+
"\n",
121+
"get the latest data from the remote repository and update your branch\n",
122+
" \n",
123+
" git pull\n",
124+
"\n",
125+
"Once you have set up everything (including pre-commit hooks) you will be able to:\n",
126+
"\n",
127+
"see your locally modified files\n",
128+
"\n",
129+
" git status\n",
130+
"\n",
131+
"add changes you want to include in the commit\n",
132+
"\n",
133+
" git add climada/modified_file.py climada/test/test_modified_file.py\n",
134+
"\n",
135+
"commit the changes\n",
136+
"\n",
137+
" git commit -m \"new functionality of .. implemented\""
138+
]
139+
},
72140
{
73141
"cell_type": "markdown",
74142
"metadata": {},
@@ -161,44 +229,9 @@
161229
"cell_type": "markdown",
162230
"metadata": {},
163231
"source": [
164-
"## Working on feature branches\n",
165-
"\n",
166-
"When developing a big new feature, consider creating a feature branch and merging smaller branches into that feature branch with pull requests, keeping the whole process separate from `develop` until it's completed. This makes step-by-step code review nice and easy, and makes the final merge more easily tracked in the history.\n",
167-
"\n",
168-
"e.g. developing the big `feature/meteorite` module you might write `feature/meteorite-hazard` and merge it in, then `feature/meteorite-impact`, then `feature/meteorite-stochastic-events` etc... before finally merging `feature/meteorite` into `develop`. Each of these could be a reviewable pull request.\n",
169-
"\n",
170-
"### Make a new **branch**\n",
171-
"\n",
172-
"For new features in Git flow:\n",
173-
"\n",
174-
" git flow feature start feature_name\n",
175-
" \n",
176-
"Which is equivalent to (in vanilla git):\n",
177-
"\n",
178-
" git checkout -b feature/feature_name\n",
179-
"\n",
180-
"Or work on an existing branch:\n",
181-
"\n",
182-
" git checkout -b branch_name\n",
183-
"\n",
184-
"get the latest data from the remote repository and update your branch\n",
185-
" \n",
186-
" git pull\n",
187-
"\n",
188-
"see your locally modified files\n",
189-
"\n",
190-
" git status\n",
191-
"\n",
192-
"add changes you want to include in the commit\n",
193-
"\n",
194-
" git add climada/modified_file.py climada/test/test_modified_file.py\n",
195-
"\n",
196-
"commit the changes\n",
197-
"\n",
198-
" git commit -m \"new functionality of .. implemented\"\n",
199-
" \n",
200232
"### Make unit and integration tests on your code, preferably during development\n",
201-
"see [Guide on unit and integration tests](Guide_Testing.ipynb)\n"
233+
"\n",
234+
"Writing new code requires writing new tests: Please read our [Guide on unit and integration tests](Guide_Testing.ipynb)"
202235
]
203236
},
204237
{

‎doc/development/Guide_Review.ipynb‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,32 @@
5252
"- If you decide to help the author with changes, you can either push them to the same branch, or create a new branch and make a pull request with the changes back into the branch you're reviewing. This lets the author review it and merge."
5353
]
5454
},
55+
{
56+
"cell_type": "markdown",
57+
"metadata": {},
58+
"source": [
59+
"## Setup the environment"
60+
]
61+
},
62+
{
63+
"cell_type": "markdown",
64+
"metadata": {},
65+
"source": [
66+
"This is a generic set of instruction which should always work.\n",
67+
"\n",
68+
"Assuming you already cloned the climada repository, and are at the root of that folder:\n",
69+
"\n",
70+
"```\n",
71+
"git fetch && git checkout <branch to review>\n",
72+
"mamba create -n <choose a name> # restrict python version here with \"python==3.x.*\"\n",
73+
"mamba env update -n <same name> -f requirements/env_climada.yml\n",
74+
"mamba activate <same name>\n",
75+
"pip install -e ./\n",
76+
"```\n",
77+
"\n",
78+
"Creating a new python environment is strongly recommended, but not always necessary (*e.g.*, for minor feature branch that do not change the dependencies you can probably use a generic `develop` environment where you installed climada in editable mode)"
79+
]
80+
},
5581
{
5682
"cell_type": "markdown",
5783
"metadata": {},
@@ -123,6 +149,13 @@
123149
" obviously inefficient (computation time-wise and memory-wise) parts in\n",
124150
" the code?"
125151
]
152+
},
153+
{
154+
"cell_type": "code",
155+
"execution_count": null,
156+
"metadata": {},
157+
"outputs": [],
158+
"source": []
126159
}
127160
],
128161
"metadata": {

‎doc/getting-started/install.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -121,11 +121,11 @@ These instructions will install the most recent stable version of CLIMADA withou
121121
122122
.. _install-advanced:
123123

124-
---------------------
125-
Advanced Instructions
126-
---------------------
124+
---------------------------------------------
125+
Advanced Instructions: Installing from source
126+
---------------------------------------------
127127

128-
For advanced Python users or developers of CLIMADA, we recommed cloning the CLIMADA repository and installing the package from source.
128+
For advanced Python users or developers of CLIMADA, cloning the CLIMADA repository and installing the package from source.
129129

130130
.. warning::
131131

@@ -214,6 +214,8 @@ For advanced Python users or developers of CLIMADA, we recommed cloning the CLIM
214214
The ``-e`` (for "editable") option further instructs ``pip`` to link to the source files instead of copying them during installation.
215215
This means that any changes to the source files will have immediate effects in your environment, and re-installing the module is never required.
216216

217+
Further note that this works only for the source files not for the dependencies. If you change the latter, you will need to update the environment with step 6. !
218+
217219
#. Verify that everything is installed correctly by executing a single test:
218220

219221
.. code-block:: shell

0 commit comments

Comments
 (0)