forked from astro-datalab/notebooks-latest
-
Notifications
You must be signed in to change notification settings - Fork 0
/
CONTRIBUTING
129 lines (81 loc) · 4.22 KB
/
CONTRIBUTING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
Version of this file: 20220218
HOW TO CONTRIBUTE NOTEBOOKS TO ASTRO DATA LAB
=============================================
We very much welcome user-contributed notebooks to Data Lab.
A few words about rules and intent
----------------------------------
- Your notebook should demonstrate or cover a case that is different
from those covered in other notebooks in the same repository.
- You agree that your contributed notebook moves into the public
domain, i.e. that anyone can propose to change it (via pull
requests).
- You maintain your claim to fame by including your name and email in
the first cell of the notebook. Your name will never be
removed. Other names may be added when the notebook is changed.
- Your notebook must roughly follow the template which we provide.
- Any notebook you add must be in ready form, i.e. all cells must run
correctly, and the notebook must be 'cleaned'. ESPECIALLY: it must
not contain any passwords or tokens.
The steps to contributing
-------------------------
You can develop your notebook either in the Astro Data Lab notebook
server or locally on your machine.
In either case, when your notebook is ready to go, you will have to
make a pull request on GitHub, so that the Data Lab team can review
and accept your notebook.
* If you want to develop on the Data Lab notebook server:
- Start your notebook server at https://datalab.noirlab.edu/devbooks
- Copy notebooks-latest/DataLabNotebookTemplate.ipynb to some other place and rename it
- Develop the notebook
* If you want to develop on your own machine:
- Install the datalab client code
pip install --upgrade astro-datalab
More detailed instructions: https://github.com/astro-datalab/datalab (the README.md file)
- Fork the 'notebooks-latest' repository on GitHub
Log in to GitHub, go to https://github.com/astro-datalab/notebooks-latest
Click on "Fork" in the upper right corner.
The forked repository will be under https://github.com/youongithub/notebooks-latest.git
where 'youongithub' is your GitHub user name.
- Clone from your fork
On your local machine:
cd foo # some local directory
git clone https://github.com/youongithub/notebooks-latest.git
* Your contributed notebook goes inside the '05_Contrib/' directory
Decide where under '05_Contrib/' your notebook will live.
For instance:
mkdir -p 05_Contrib/ExtraGalactic/InterestingScienceCase/
cd 05_Contrib/ExtraGalactic/InterestingScienceCase/
cp ../../DataLabNotebookTemplate.ipynb InterestingScienceCase.ipynb
Some advice:
- Use your judgment where to place you notebook under 05_Contrib/.
- If it does not fit under any existing rubric
(e.g. 'ExtraGalactic/', 'SolarSystem/', etc.), start a new one,
i.e. make the sub-directory and place your notebook there.
- Your notebook must be in a stand-alone sub(sub)directory of its own
E.g. 05_Contrib/ExtraGalactic/LensingEinsteinCross/
or 05_Contrib/ExtraGalactic/MicroLensing/
- Place auxiliary files (if any) there as well, e.g. external data
tables used in your notebook, image files, etc. Make sure to keep
their size small.
* Develop and test your notebook
Make sure that your notebook:
- Follows the rough structure, and the instructions in the DL notebook template.
- Runs (all cells).
- Is clean, and free of cruft.
- Has no passwords or tokens, or any other sensitive information.
- Uses keywords from the list in ./keywords.txt
If you need new keywords, add them to the list.
* Add the notebook and any aux files to your git tracking
E.g.
git add 05_Contrib/ExtraGalactic/SuperScienceCase/SuperScienceCase.ipynb
* Commit to your master
git commit -a -m "Add contributed science case notebook on XYZ science"
* Push to your fork on GitHub
git push origin master
* Make a pull request (PR) on GitHub:
- Go to your fork of notebooks-latest on GitHub
- Click on "New pull request", and follow the instructions
The DL team will review your notebook and either suggest some
changes or accept the PR. Once accepted, your notebook will become
part of the default set of notebooks delivered with DL.
As always, please ask the DL team any questions you have at <[email protected]>