@@ -11,6 +11,137 @@ Contributing to xbatcher
1111 on the `Pandas Contributing Guide
1212 <http://pandas.pydata.org/pandas-docs/stable/contributing.html> `_.
1313
14+ Bug reports and feature requests
15+ ================================
16+
17+ To report bugs or request new features, head over to the `xbatcher repository
18+ <https://github.com/pangeo-data/xbatcher/issues> `_.
19+
20+ Contributing code
21+ ==================
22+
23+ `GitHub has instructions <https://help.github.com/set-up-git-redirect >`__ for
24+ installing git, setting up your SSH key, and configuring git. All these steps
25+ need to be completed for you to work between your local repository and GitHub.
26+
27+ .. _contributing.forking :
28+
29+ Forking
30+ -------
31+
32+ You will need your own fork to work on the code. Go to the `xbatcher project
33+ page <https://github.com/pangeo-data/xbatcher> `_ and hit the ``Fork `` button.
34+ You will need to clone your fork to your machine::
35+
36+ git clone [email protected] :yourusername/xbatcher.git 37+ cd xbatcher
38+ git remote add upstream [email protected] :pangeo-data/xbatcher.git 39+
40+ This creates the directory ``xbatcher `` and connects your repository to
41+ the upstream (main project) *xbatcher * repository.
42+
43+ .. _contributing.dev_env :
44+
45+ Creating a development environment
46+ ----------------------------------
47+
48+ To test out code changes, you'll need to build *xbatcher * from source, which
49+ requires a Python environment. If you're making documentation changes, you can
50+ skip to :ref: `contributing.documentation ` but you won't be able to build the
51+ documentation locally before pushing your changes.
52+
53+ .. _contributiong.dev_python :
54+
55+ Creating a Python Environment
56+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57+
58+ Before starting any development, you'll need to create an isolated xbatcher
59+ development environment:
60+
61+ - Install either `Anaconda <https://www.anaconda.com/download/ >`_ or `miniconda
62+ <https://conda.io/miniconda.html> `_
63+ - Make sure your conda is up to date (``conda update conda ``)
64+ - Make sure that you have :ref: `cloned the repository <contributing.forking >`
65+ - ``cd `` to the *xbatcher * source directory
66+
67+ First we'll create and activate the build environment:
68+
69+ .. code-block :: sh
70+
71+ conda env create --file ci/requirements/environment.yml
72+ conda activate xbatcher-tests
73+
74+ xbatcher * from your locally
75+ built version:
76+
77+ .. code-block :: sh
78+
79+ $ python # start an interpreter
80+ >>> import xbatcher
81+ >>> xbatcher.__version__
82+
83+
84+ nor any existing Python installation.
85+
86+ To view your environments::
87+
88+ conda info --envs
89+
90+ To return to your base environment::
91+
92+ conda deactivate
93+
94+ See the full conda docs `here <http://conda.pydata.org/docs >`__.
95+
96+ Setting up pre-commit
97+ ~~~~~~~~~~~~~~~~~~~~~
98+
99+ We use `pre-commit <https://pre-commit.com/ >`_ to manage code linting and style.
100+ To set up pre-commit after activating your conda environment, run:
101+
102+ .. code-block :: sh
103+
104+ pre-commit install
105+
106+
107+ -----------------
108+
109+ You want your ``main `` branch to reflect only production-ready code, so create a
110+ feature branch before making your changes. For example::
111+
112+ git branch shiny-new-feature
113+ git checkout shiny-new-feature
114+
115+ The above can be simplified to::
116+
117+ git checkout -b shiny-new-feature
118+
119+ This changes your working directory to the shiny-new-feature branch. Keep any
120+ changes in this branch specific to one bug or feature so it is clear
121+ what the branch brings to *xbatcher *. You can have many "shiny-new-features"
122+ and switch in between them using the ``git checkout `` command.
123+
124+ To update this branch, you need to retrieve the changes from the ``main `` branch::
125+
126+ git fetch upstream
127+ git merge upstream/main
128+
129+ This will combine your commits with the latest *xbatcher * git ``main ``. If this
130+ leads to merge conflicts, you must resolve these before submitting your pull
131+ request. If you have uncommitted changes, you will need to ``git stash `` them
132+ prior to updating. This will effectively store your changes, which can be
133+ reapplied after updating.
134+
135+ Running the test suite
136+ ----------------------
137+
138+ *xbatcher * uses the `pytest <https://docs.pytest.org/en/latest/contents.html >`_
139+ framework for testing. You can run the test suite using::
140+
141+ pytest xbatcher
142+
143+
144+
14145Running the performance test suite
15146----------------------------------
16147
@@ -53,3 +184,65 @@ will only run the ``Generator.time_batch_preload`` benchmark defined in
53184
54185Information on how to write a benchmark and how to use asv can be found in the
55186`asv documentation <https://asv.readthedocs.io/en/latest/writing_benchmarks.html >`_.
187+
188+ Contributing documentation
189+ ==========================
190+
191+ We greatly appreciate documentation improvements. The docs are built from the docstrings
192+ in the code and the docs in the ``doc `` directory.
193+
194+ To build the documentation, you will need to requirements listed in ``ci/requirements/doc.yml ``.
195+ You can create an environment for building the documentation using::
196+
197+ conda env create --file ci/requirements/docs.yml
198+ conda activate xbatcher-docs
199+
200+ You can then build the documentation using::
201+
202+ cd docs
203+ make html
204+
205+ Contributing changes
206+ ====================
207+
208+ Once you've made changes, you can see them by typing::
209+
210+ git status
211+
212+ If you have created a new file, it is not being tracked by git. Add it by typing::
213+
214+ git add path/to/file-to-be-added.py
215+
216+ The following defines how a commit message should be structured:
217+
218+ * A subject line with `< 72 ` chars.
219+ * One blank line.
220+ * Optionally, a commit message body.
221+
222+ Now you can commit your changes in your local repository::
223+
224+ git commit -m
225+
226+ When you want your changes to appear publicly on your GitHub page, push your
227+ commits to a branch off your fork::
228+
229+ git push origin shiny-new-feature
230+
231+ Here ``origin `` is the default name given to your remote repository on GitHub.
232+ You can see the remote repositories::
233+
234+ git remote -v
235+
236+ If you navigate to your branch on GitHub, you should see a banner to submit a pull
237+ request to the *xbatcher * repository.
238+
239+ .. _contributing.ci :
240+
241+ Continuous integration
242+ ======================
243+
244+ Continuous integration is done with `GitHub Actions <https://docs.github.com/en/actions/learn-github-actions >`_.
245+
246+ There is currently 1 workflow configured:
247+
248+ - `main.yaml <https://github.com/pangeo-data/xbatcher/blob/main/.github/workflows/main.yaml >`_ - Run test suite with pytest.
0 commit comments