3431 dev guide

CONTRIBUTING.md

@@ -28,7 +28,7 @@ An issue is a bug (a feature is no longer behaving the way it should) or a featu
 
 Before submitting an issue, please search the existing issues by using the search bar at the top of the page. If there is an existing issue that matches the issue you want to report, please add a comment to it.
 
-If there is no pre-existing issue, please click on the "New Issue" button, log in, and write in what the issue is (unless it is a security issue which should be reported privately to security@dataverse.org). Someone on the Dataverse development team will appropriately tag and assign it to a member of the Dataverse development team.
+If there is no pre-existing issue, please click on the "New Issue" button, log in, and write in what the issue is (unless it is a security issue which should be reported privately to security@dataverse.org).
 
 If you do not receive a reply to your new issue or comment in a timely manner, please email support@dataverse.org with a link to the issue.
 
@@ -53,12 +53,11 @@ The source for the documentation at http://guides.dataverse.org is in the GitHub
 
 Before you start coding, please reach out to us either on the [dataverse-community Google Group][], the [dataverse-dev Google Group][], [IRC][] (#dataverse on freenode), or via support@dataverse.org to make sure the effort is well coordinated and we avoid merge conflicts.
 
-We will encourage you to create a GitHub issue (if it doesn't exist already) to associate with your pull request.
+Please read http://guides.dataverse.org/en/latest/developers/version-control.html to understand how we use the "git flow" model of development and how we will encourage you to create a GitHub issue (if it doesn't exist already) to associate with your pull request.
 
-We hope you find the Developer Guide at http://guides.dataverse.org/en/latest/developers helpful.
-
-After making your pull request, your goal should be to help it advance through our kanban board at https://waffle.io/IQSS/dataverse . If no one has moved your pull request to the code review column in a timely manner, please reach out. Thanks!
+After making your pull request, your goal should be to help it advance through our kanban board at https://waffle.io/IQSS/dataverse . If no one has moved your pull request to the code review column in a timely manner, please reach out. We maintain a list of [community contributors][] so please let us know if you'd like to be added or removed from the list. Thanks!
 
 [dataverse-community Google Group]: https://groups.google.com/group/dataverse-community
 [dataverse-dev Google Group]: https://groups.google.com/group/dataverse-dev
 [IRC]: http://chat.dataverse.org
+[community contributors]: https://docs.google.com/spreadsheets/d/1o9DD-MQ0WkrYaEFTD5rF_NtyL8aUISgURsAXSL7Budk/edit?usp=sharing

PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,7 @@ Welcome! New contributors should at least glance at [CONTRIBUTING.md](/CONTRIBUT
 
 ## Related Issues
 
-- connects to [#issue number]: [issue title]
+- connects to #ISSUE_NUMBER: ISSUE_TITLE
 
 ## Pull Request Checklist
 

README.md

@@ -1,20 +1,36 @@
 Dataverse®
 ===============
 
-Dataverse is an open source web application for sharing, citing, analyzing, and preserving research data (developed by the [Data Science and Products team](http://www.iq.harvard.edu/people/people/data-science-products) at the [Institute for Quantitative Social Science](http://iq.harvard.edu/)).
+Dataverse is an [open source][] web application for sharing, citing, analyzing, and preserving research data (developed by the [Data Science and Products team](http://www.iq.harvard.edu/people/people/data-science-products) at the [Institute for Quantitative Social Science](http://iq.harvard.edu/) and the [Dataverse community][]).
 
-Institutions and organizations can choose to install the Dataverse software for their own use. 
-In this case, the institution will be responsible for maintaining the application; installing upgrades, 
-setting up backups and data replication as needed. Dataverse 4.0 is now released and used by the Harvard Dataverse: [dataverse.harvard.edu](http://dataverse.harvard.edu/). If you'd like to first test it, you can use our demo site: [demo.dataverse.org](http://demo.dataverse.org).
+[dataverse.org][] is our home on the web and shows a map of Dataverse installations around the world, a list of [features][], [integrations][] that have been made possible through [REST APIs][], our development [roadmap][], and more.
 
-For more general information about Dataverse please visit [dataverse.org](http://dataverse.org). 
+We maintain a demo site at [demo.dataverse.org][] which you are welcome to use for testing and evaluating Dataverse.
 
-The Dataverse code is *open-source* and *free*. 
+To install Dataverse, please see our [Installation Guide][] which will prompt you to download our [latest release][].
 
-Dataverse releases are available for download from https://github.com/IQSS/dataverse/releases and installation instructions can be found in the [Installation Guide](http://guides.dataverse.org/en/latest/installation/).
+To discuss Dataverse with the community, please join our [mailing list][], participate in a [community call][], chat with us at [chat.dataverse.org][], or attend our annual [Dataverse Community Meeting][].
+
+We love contributors! Please see our [Contributing Guide][] for ways you can help.
 
 Dataverse is a trademark of President and Fellows of Harvard College and is registered in the United States.
 
 [![Dataverse Project logo](src/main/webapp/resources/images/dataverseproject_logo.jpg?raw=true "Dataverse Project")](http://dataverse.org)
 
-[![Build Status](https://travis-ci.org/IQSS/dataverse.svg?branch=master)](https://travis-ci.org/IQSS/dataverse) [![Coverage Status](https://coveralls.io/repos/IQSS/dataverse/badge.svg?branch=master&service=github)](https://coveralls.io/github/IQSS/dataverse?branch=master)
+[![Build Status](https://travis-ci.org/IQSS/dataverse.svg?branch=develop)](https://travis-ci.org/IQSS/dataverse) [![Coverage Status](https://coveralls.io/repos/IQSS/dataverse/badge.svg?branch=develop&service=github)](https://coveralls.io/github/IQSS/dataverse?branch=develop)
+
+[dataverse.org]: https://dataverse.org
+[demo.dataverse.org]: https://demo.dataverse.org
+[Dataverse community]: https://dataverse.org/developers
+[Installation Guide]: http://guides.dataverse.org/en/latest/installation/index.html
+[latest release]: https://github.com/IQSS/dataverse/releases
+[features]: https://dataverse.org/software-features
+[roadmap]: https://dataverse.org/goals-roadmap-and-releases
+[integrations]: https://dataverse.org/integrations
+[REST APIs]: http://guides.dataverse.org/en/latest/api/index.html
+[Contributing Guide]: CONTRIBUTING.md
+[mailing list]: https://groups.google.com/group/dataverse-community
+[community call]: https://dataverse.org/community-calls
+[chat.dataverse.org]: http://chat.dataverse.org
+[Dataverse Community Meeting]: https://dataverse.org/events
+[open source]: LICENSE.md

doc/sphinx-guides/source/developers/coding-style.rst

@@ -2,11 +2,66 @@
 Coding Style
 ============
 
+Like all development teams, the `Dataverse developers at IQSS <https://dataverse.org/about>`_ have their habits and styles when it comes to writing code. Let's attempt to get on the same page. :)
+
 .. contents:: |toctitle|
 	:local:
 
-Like all development teams, the `Dataverse developers at IQSS <http://datascience.iq.harvard.edu/team>`_ have their habits and styles when it comes to writing code.
+Java
+----
+
+Formatting Code
+~~~~~~~~~~~~~~~
+
+Tabs vs. Spaces
+^^^^^^^^^^^^^^^
+
+Don't use tabs. Use spaces.
+
+Format Code You Changed with Netbeans
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As you probably gathered from the :doc:`dev-environment` section, IQSS has standardized on Netbeans. It is much appreciated when you format your code (but only the code you touched!) using the out-of-the-box Netbeans configuration. If you have created an entirely new Java class, you can just click Source -> Format. If you are adjusting code in an existing class, highlight the code you changed and then click Source -> Format. Keeping the "diff" in your pull requests small makes them easier to code review.
+
+We would like to someday automate the detection and possibly correction of code that hasn't been formatted using our house style (the default Netbeans style). We've heard that https://maven.apache.org/plugins/maven-checkstyle-plugin/ can do this but we would be happy to see a pull request in this area, especially if it also hooks up to our builds at https://travis-ci.org/IQSS/dataverse .
+
+Logging
+~~~~~~~
+
+We have adopted a pattern where the top of every class file has a line like this::
+
+    private static final Logger logger = Logger.getLogger(DatasetUtil.class.getCanonicalName());
+
+Use this ``logger`` field with varying levels such as ``fine`` or ``info`` like this::
+
+    logger.fine("will get thumbnail from dataset logo");
+
+Generally speaking you should use ``fine`` for everything that you don't want to show up in Glassfish's ``server.log`` file by default. If you use a higher level such as ``info`` for common operations, you will probably hear complaints that your code is too "chatty" in the logs. These logging levels can be controlled at runtime both on your development machine and in production as explained in the :doc:`debugging` section.
+
+When adding logging, do not simply add ``System.out.println()`` lines because the logging level cannot be controlled.
+
+Avoid Hard-Coding Strings
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Special strings should be defined as public constants. For example, ``DatasetFieldConstant.java`` contains a field for "title" and it's used in many places in the code (try "Find Usages" in Netbeans). This is better than writing the string "title" in all those places.
+
+Type Safety
+~~~~~~~~~~~
+
+If you just downloaded Netbeans and are using the out-of-the-box settings, you should be in pretty good shape. Unfortunately, the default configuration of Netbeans doesn't warn you about type-safety problems you may be inadvertently introducing into the code. To see these warnings, click Netbeans -> Preferences -> Editor -> Hints and check the following:
+
+- "Raw Types" under "Standard Javac Warnings"
+
+If you know of a way to easily share Netbeans configuration across a team, please get in touch.
+
+
+Bike Shedding
+-------------
+
+What color should the `bike shed <https://en.wiktionary.org/wiki/bikeshedding>`_ be? :)
+
+Come debate with us about coding style in this Google doc that has public comments enabled: https://docs.google.com/document/d/1KTd3FpM1BI3HlBofaZjMmBiQEJtFf11jiiGpQeJzy7A/edit?usp=sharing
 
-A lot of it isn't written down, but a draft has been started at https://docs.google.com/document/d/1KTd3FpM1BI3HlBofaZjMmBiQEJtFf11jiiGpQeJzy7A/edit?usp=sharing
+----
 
-Debate and comments are welcome!
+Previous: :doc:`debugging` | Next: :doc:`making-releases`

doc/sphinx-guides/source/developers/debugging.rst

@@ -9,3 +9,7 @@ Logging
 -------
 
 By default, Glassfish logs at the "INFO" level but logging can be increased to "FINE" on the fly with (for example) ``asadmin set-log-levels edu.harvard.iq.dataverse.api.Datasets=FINE``. Running ``asadmin list-log-levels`` will show the current logging levels.
+
+----
+
+Previous: :doc:`documentation` | Next: :doc:`coding-style`