|
1 | | -# Contributing to the MarkLogic Node.js Client API |
| 1 | +# Contributing to the MarkLogic Node.js Client |
2 | 2 |
|
3 | | -The MarkLogic Node.js Client API welcomes new contributors. This document will guide you |
4 | | -through the process. |
| 3 | +This guide describes how to develop and test the Node.js Client. For questions about how to use the Node.js Client API, |
| 4 | +please see the README file. |
5 | 5 |
|
6 | | - - [Question or Problem?](#question) |
7 | | - - [Issues and Bugs](#issue) |
8 | | - - [Feature Requests](#feature) |
9 | | - - [Submission Guidelines](#submit) |
10 | 6 |
|
11 | | -## <a name="question"></a> Have a Question or Problem? |
| 7 | +## Initial Setup |
12 | 8 |
|
13 | | -If you have questions about how to use the Node.js Client API, you can ask on |
14 | | -[StackOverflow](http://stackoverflow.com/tags/marklogic), tagging the question |
15 | | -with MarkLogic. |
| 9 | +To run any of the steps below, first verify that you have the following available; |
| 10 | +[sdkman](https://sdkman.io/) is recommended for installing and maintaining versions of Java: |
| 11 | +* Java 8.x |
16 | 12 |
|
17 | | -## <a name="issue"></a> Found an Issue? |
18 | | -If you find a bug in the source code or a mistake in the documentation, you can help us by |
19 | | -submitting an issue to our [GitHub Issue Tracker](https://github.com/marklogic/node-client-api/issues). Even better |
20 | | -you can submit a Pull Request with a fix for the issue you filed. |
| 13 | +You will also need to clone this repository locally and open a CLI in the root directory of the cloned project. |
21 | 14 |
|
22 | | -## <a name="feature"></a> Want a Feature? |
23 | | -You can request a new feature by submitting an issue to our [GitHub Issue Tracker](https://github.com/marklogic/node-client-api/issues). If you would like to implement a new feature, first create a new issue and discuss it with one of our project |
24 | | -maintainers. |
| 15 | +[Docker Desktop](https://www.docker.com/products/docker-desktop/) is recommended for automating and simplifying the setup for developing and testing the connector. |
| 16 | +Without it, you can still deploy the test app to your local MarkLogic instance and run the tests, but it could cause |
| 17 | +conflicts with other MarkLogic AppServers and/or databases. |
25 | 18 |
|
26 | | -## <a name="submit"></a> Submission Guidelines |
| 19 | +If you are not using Docker, you can skip to the next section, the assumption being that you have a MarkLogic |
| 20 | +instance available for testing. |
27 | 21 |
|
28 | | -### Submitting an Issue |
29 | | -If your issue appears to be a bug, and hasn’t been reported, open a new issue. |
30 | | -Providing the following information will increase the chances of your issue being dealt with quickly: |
| 22 | +If you are able to use Docker, run the following: |
31 | 23 |
|
32 | | -* **Overview of the Issue** - If an error is being thrown a stack trace helps |
33 | | -* **Motivation for or Use Case** - Explain why this is a bug for you |
34 | | -* **Environment** - Which [version of MarkLogic](https://docs.marklogic.com/xdmp.version)? Which version of the Node.js Client API? Mac, Windows, Linux? Details help. |
35 | | -* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point |
36 | | -to what might be causing the problem (line of code or commit) |
| 24 | + cd test-app |
| 25 | + docker-compose up -d --build |
37 | 26 |
|
38 | | -### Submitting a Pull Request |
| 27 | +This will create a container with the MarkLogic service. The MarkLogic service will take a minute or two to initialize. |
| 28 | +Point your browser to http://localhost:8001 to verify that the service is running and has been initialized. The default |
| 29 | +username and password are in the docker-compose.yaml file in the /test-app directory. |
39 | 30 |
|
40 | | -A pull request is the standard way to submit changes to a repository to which you don’t have commit privileges. GitHub provides a nice UI for viewing, discussing, and merging pull requests. |
| 31 | +Once the container is finished initializing, you need to deploy the test application to the MarkLogic service. |
| 32 | +While still in the test-app directory run the following gradle command. |
41 | 33 |
|
42 | | -#### Fill in the CLA |
| 34 | + ./gradlew -i mlDeploy |
43 | 35 |
|
44 | | -Before we can accept your pull request, you need to sign a [Contributor License Agreement](http://developer.marklogic.com/products/cla). |
| 36 | +Once the deploy has completed successfully, use "cd .." to return to the root directory of the project. |
45 | 37 |
|
46 | | -#### Fork the Node.js Client API |
47 | 38 |
|
48 | | -Fork the project [on GitHub](https://github.com/marklogic/node-client-api/fork) |
49 | | -and clone your copy. |
| 39 | +## Running the test suite |
50 | 40 |
|
51 | | - $ git clone [email protected]:username/node-client-api.git |
52 | | - $ cd node-client-api |
53 | | - $ git remote add upstream git://github.com/marklogic/node-client-api.git |
| 41 | +To run the tests contained in the project, you will need to install Mocha globally. This only needs to be done once. |
54 | 42 |
|
55 | | -All bug fixes and new features go into the `develop` branch. |
| 43 | + npm install mocha -g |
56 | 44 |
|
57 | | -We ask that you open an issue in the [issue tracker](https://github.com/marklogic/node-client-api/issues) and get agreement from at least one of the project maintainers before you start coding. |
| 45 | +Once Mocha has been installed, you can run the entire test suite with this command. This will take several minutes to complete. |
58 | 46 |
|
59 | | -Nothing is more frustrating than seeing your hard work go to waste because your vision does not align with that of a project maintainer. |
| 47 | + mocha test-basic -timeout 0 |
60 | 48 |
|
61 | | -#### Create a branch for your changes |
| 49 | +Alternatively, to run a single test or a single "describe" group of tests, use this command with the description text |
| 50 | +contained in either the "it" function or the "describe" function, respectively. |
62 | 51 |
|
63 | | -Okay, so you have decided to fix something. Create a feature branch and start hacking: |
| 52 | + mocha test-basic -timeout 0 -g 'optic-update fromParam tests' |
| 53 | +or |
64 | 54 |
|
65 | | - $ git checkout -b issue/123 -t origin/dev |
66 | | - |
67 | | -In this case, the branch name, `issue/123`, references the fact that your changes address the issue (#123) that you just filed. Replace the `123` with your issue number. This naming convention is not required, but is generally helpful in navigating your branches. |
68 | | - |
69 | | -#### Commit your changes |
70 | | - |
71 | | -Make sure git knows your name and email address: |
72 | | - |
73 | | - $ git config --global user.name "J. Random User" |
74 | | - $ git config --global user.email "[email protected]" |
75 | | - |
76 | | -Writing good commit logs is important. A commit log should describe what changed and why. Follow these guidelines when writing one: |
77 | | - |
78 | | -1. The first line should be 50 characters or less and contain a short description of the change including the Issue number prefixed by a hash (`#`). |
79 | | -2. Keep the second line blank. |
80 | | -3. Wrap all other lines at 72 columns. |
81 | | - |
82 | | -A good commit log looks like this: |
83 | | - |
84 | | -``` |
85 | | -Fixes #123: Makes the whatchamajigger work in MarkLogic 8 |
86 | | -
|
87 | | -Body of commit message is a few lines of text, explaining things |
88 | | -in more detail, possibly giving some background about the issue |
89 | | -being fixed, etc etc. |
90 | | -
|
91 | | -The body of the commit message can be several paragraphs, and |
92 | | -please do proper word-wrap and keep columns shorter than about |
93 | | -72 characters or so. That way `git log` will show things |
94 | | -nicely even when it is indented. |
95 | | -``` |
96 | | - |
97 | | -The header line should be meaningful; it is what other people see when they |
98 | | -run `git shortlog` or `git log --oneline`. |
99 | | - |
100 | | -#### Rebase your repo |
101 | | - |
102 | | -Use `git rebase` (not `git merge`) to sync your work from time to time to make sure you don’t stray too far from the active development work. |
103 | | - |
104 | | - $ git fetch upstream |
105 | | - $ git rebase upstream/develop |
106 | | - |
107 | | -#### Test your code |
108 | | - |
109 | | -Be sure to run the tests before submitting your pull request. PRs with failing tests won’t be accepted. |
110 | | - |
111 | | - $ node etc/test-setup.js |
112 | | - $ mocha test-basic |
113 | | - $ node etc/test-teardown.js |
114 | | - |
115 | | -#### Push your changes |
116 | | - |
117 | | - $ git push origin issue/123 |
118 | | - |
119 | | -#### Submit the pull request |
120 | | - |
121 | | -Go to your fork (i.e. https://github.com/username/node-client-api) and select your feature branch. Click the “Pull Request” button and fill out the form. |
122 | | - |
123 | | -Pull requests are usually reviewed within a few days. If you get comments that need to be to addressed, apply your changes in a separate commit and push that to your feature branch. Post a comment in the pull request afterwards; GitHub does not send out notifications when you add commits to existing pull requests. |
124 | | - |
125 | | -That’s it. Thanks in advance for your contribution. |
126 | | - |
127 | | - |
128 | | -#### After your pull request is merged |
129 | | - |
130 | | -After your pull request is merged, you can safely delete your branch and pull |
131 | | -the changes from the main (upstream) repository: |
132 | | - |
133 | | -* Delete the remote branch on GitHub either through the GitHub web UI or your |
134 | | -local shell as follows: |
135 | | - |
136 | | - $ git push origin --delete issue/123 |
137 | | - |
138 | | -* Check out the dev branch: |
139 | | - |
140 | | - $ git checkout develop -f |
141 | | - |
142 | | -* Delete the local branch: |
143 | | - |
144 | | - $ git branch -D issue/123 |
145 | | - |
146 | | -* Update your dev with the latest upstream version: |
147 | | - |
148 | | - $ git pull --ff upstream develop |
| 55 | + mocha test-basic -timeout 0 -g 'test bindParam with qualifier' |
0 commit comments