|
| 1 | +<img src="http://developer.postgresql.org/~josh/graphics/logos/elephant-64.png" /> |
| 2 | +# Parent poms for PostgreSQL JDBC driver |
| 3 | + |
| 4 | +[](https://travis-ci.org/pgjdbc/pgjdbc-parent-poms) |
| 5 | + |
| 6 | +This repository includes maven parent poms that are used by PostgreSQL JDBC driver. |
| 7 | + |
| 8 | +## Info |
| 9 | + |
| 10 | +You probably do not need to clone/build this repository. |
| 11 | +In order to contribute a feature / file a bug report for JDBC driver, please use [JDBC driver](http://github.com/pgjdbc/pgjdbc) main repository. |
| 12 | + |
| 13 | +In case base dependency (e.g. `maven-compiler-plugin` version) needs to be changed, a relevant change to the `pgjdbc-parent-poms` repository should |
| 14 | +be made and this new version should be used in main `pgjdbc` repository. |
| 15 | + |
| 16 | +## Downloading pre-built drivers |
| 17 | + |
| 18 | +Most people do not need to compile PgJDBC. You can download prebuilt versions of the driver |
| 19 | +from the [Postgresql JDBC site](http://jdbc.postgresql.org/) or using your chosen dependency management tool |
| 20 | +(see details at [JDBC driver](http://github.com/pgjdbc/pgjdbc) ) |
| 21 | + |
| 22 | +## Build requirements |
| 23 | + |
| 24 | +In order to build the set of parent poms, you will need the following tools: |
| 25 | + |
| 26 | +- A git client |
| 27 | +- A recent version of Maven (3.x) |
| 28 | +- A JDK (any should work) |
| 29 | + |
| 30 | +## Checking out the source code |
| 31 | + |
| 32 | +The PgJDBC project uses git for version control. You can check out the current code by running: |
| 33 | + |
| 34 | + git clone https://github.com/pgjdbc/pgjdbc-parent-poms.git |
| 35 | + |
| 36 | +This will create a pgjdbc-parent-poms directory containing the checked-out source code. |
| 37 | + |
| 38 | +## Installing parent poms to local repository |
| 39 | + |
| 40 | +After checking out the code you can install new poms to your local repository: |
| 41 | + |
| 42 | + mvn install |
| 43 | + |
| 44 | +## Releasing a snapshot version |
| 45 | + |
| 46 | +Git repository typically contains -SNAPSHOT versions, so you can use the following command: |
| 47 | + |
| 48 | + mvn deploy |
| 49 | + |
| 50 | +## Releasing a new version |
| 51 | + |
| 52 | +Procedure: |
| 53 | + |
| 54 | +To commit updates to version in `pom.xml` files and create a tag, issue: |
| 55 | + |
| 56 | + mvn release:clean release:prepare |
| 57 | + |
| 58 | +To release the version to maven central, issue: |
| 59 | + |
| 60 | + mvn release:release |
| 61 | + |
| 62 | +## Dependencies |
| 63 | + |
| 64 | +`pgjdbc-parent-poms` has little to no dependencies itself. It just lists defaults to be used by core `pgjdbc` project. |
| 65 | + |
| 66 | +## Bug reports, patches and development |
| 67 | + |
| 68 | +PgJDBC development is carried out on the [PgJDBC mailing list](https://jdbc.postgresql.org/community/mailinglist.html) and on [GitHub](https://github.com/pgjdbc/pgjdbc). |
| 69 | + |
| 70 | +### Bug reports |
| 71 | + |
| 72 | +For bug reports please post on pgsql-jdbc or add a GitHub issue. If you include |
| 73 | +additional unit tests demonstrating the issue, or self-contained runnable test |
| 74 | +case including SQL scripts etc that shows the problem, your report is likely to |
| 75 | +get more attention. Make sure you include appropriate details on your |
| 76 | +environment, like your JDK version, container/appserver if any, platform, |
| 77 | +PostgreSQL version, etc. Err on the site of excess detail if in doubt. |
| 78 | + |
| 79 | +### Bug fixes and new features |
| 80 | + |
| 81 | +If you've developed a patch you want to propose for inclusion in PgJDBC, feel |
| 82 | +free to send a GitHub pull request or post the patch on the PgJDBC mailing |
| 83 | +list. Make sure your patch includes additional unit tests demonstrating and |
| 84 | +testing any new features. In the case of bug fixes, where possible include a |
| 85 | +new unit test that failed before the fix and passes after it. |
| 86 | + |
| 87 | +For information on working with GitHub, see: http://help.github.com/articles/fork-a-repo and http://learn.github.com/p/intro.html. |
| 88 | + |
| 89 | +### Testing |
| 90 | + |
| 91 | +Remember to test proposed PgJDBC patches when running against older PostgreSQL |
| 92 | +versions where possible, not just against the PostgreSQL you use yourself. |
| 93 | + |
| 94 | +You also need to test your changes with older JDKs. PgJDBC must support JDK6 |
| 95 | +("Java 1.6") and newer. Code that is specific to a particular spec version |
| 96 | +may use features from that version of the language. i.e. JDBC4.1 specific |
| 97 | +may use JDK7 features, JDBC4.2 may use JDK8 features. |
| 98 | +Common code and JDBC4 code needs to be compiled using JDK6. |
| 99 | + |
| 100 | +### Ideas |
| 101 | + |
| 102 | +If you have ideas or proposed changes, please post on the mailing list or |
| 103 | +open a detailed, specific GitHub issue. |
| 104 | + |
| 105 | +Think about how the change would affect other users, what side effects it |
| 106 | +might have, how practical it is to implement, what implications it would |
| 107 | +have for standards compliance and security, etc. Include a detailed use-case |
| 108 | +description. |
| 109 | + |
| 110 | +Few of the PgJDBC developers have much spare time, so it's unlikely that your |
| 111 | +idea will be picked up and implemented for you. The best way to make sure a |
| 112 | +desired feature or improvement happens is to implement it yourself. The PgJDBC |
| 113 | +sources are reasonably clear and they're pure Java, so it's sometimes easier |
| 114 | +than you might expect. |
| 115 | + |
| 116 | +## Support for IDEs |
| 117 | + |
| 118 | +It's possible to debug and test PgJDBC with various IDEs, not just with `mvn` on |
| 119 | +the command line. Projects aren't supplied, but it's easy to prepare them. |
| 120 | + |
| 121 | +## <a name="commit"></a> Git Commit Guidelines |
| 122 | + |
| 123 | +We have very precise rules over how our git commit messages can be formatted. This leads to **more |
| 124 | +readable messages** that are easy to follow when looking through the **project history**. But also, |
| 125 | +we use the git commit messages to **generate the change log**. |
| 126 | + |
| 127 | +### Commit Message Format |
| 128 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special |
| 129 | +format that includes a **type**, and a **subject**: |
| 130 | + |
| 131 | +``` |
| 132 | +<type>: <subject> |
| 133 | +<BLANK LINE> |
| 134 | +<body> |
| 135 | +<BLANK LINE> |
| 136 | +<footer> |
| 137 | +``` |
| 138 | + |
| 139 | +Any line of the commit message cannot be longer 100 characters! This allows the message to be easier |
| 140 | +to read on github as well as in various git tools. |
| 141 | + |
| 142 | +### Type |
| 143 | +Must be one of the following: |
| 144 | + |
| 145 | +* **feat**: A new feature |
| 146 | +* **fix**: A bug fix |
| 147 | +* **docs**: Documentation only changes |
| 148 | +* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing |
| 149 | + semi-colons, etc) |
| 150 | +* **refactor**: A code change that neither fixes a bug or adds a feature |
| 151 | +* **perf**: A code change that improves performance |
| 152 | +* **test**: Adding missing tests |
| 153 | +* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation |
| 154 | + generation |
| 155 | + |
| 156 | +### Subject |
| 157 | +The subject contains succinct description of the change: |
| 158 | + |
| 159 | +* use the imperative, present tense: "change" not "changed" nor "changes" |
| 160 | +* don't capitalize first letter |
| 161 | +* no dot (.) at the end |
| 162 | + |
| 163 | +###Body |
| 164 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes" |
| 165 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 166 | + |
| 167 | +###Footer |
| 168 | +The footer should contain any information about **Breaking Changes** and is also the place to |
| 169 | +reference GitHub issues that this commit **Closes**. |
| 170 | + |
| 171 | + |
| 172 | +### Sponsors |
| 173 | + |
| 174 | +[PostgreSQL International](http://www.postgresintl.com) |
0 commit comments