diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1430ba951a6..4fa6e955b70 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,67 +1,7 @@ # Contributing to Dataverse -Thank you for your interest in contributing to Dataverse! We are open to contributions from everyone. You don't need permission to participate. Just jump in. If you have questions, please reach out using one or more of the channels described below. +Thank you for your interest in contributing to Dataverse! We are open to contributions from everyone. -We aren't just looking for developers. There are many ways to contribute to Dataverse. We welcome contributions of ideas, bug reports, usability research/feedback, documentation, code, and more! +Please see our [Contributor Guide][] for how you can help! -## Ideas/Feature Requests - -Your idea or feature request might already be captured in the Dataverse [issue tracker] on GitHub but if not, the best way to bring it to the community's attention is by posting on the [dataverse-community Google Group][] or bringing it up on a [Community Call][]. You're also welcome to make some noise in [chat.dataverse.org][] or cram your idea into 280 characters and mention [@dataverseorg][] on Twitter. To discuss your idea privately, please email it to support@dataverse.org - -There's a chance your idea is already on our roadmap, which is available at https://www.iq.harvard.edu/roadmap-dataverse-project - -[chat.dataverse.org]: http://chat.dataverse.org -[issue tracker]: https://github.com/IQSS/dataverse/issues -[@dataverseorg]: https://twitter.com/dataverseorg - -## Usability testing - -Please email us at support@dataverse.org if you are interested in participating in usability testing. - -## Bug Reports/Issues - -An issue is a bug (a feature is no longer behaving the way it should) or a feature (something new to Dataverse that helps users complete tasks). You can browse the Dataverse [issue tracker] on GitHub by open or closed issues or by milestones. - -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 open issue that matches the issue you want to report, please add a comment to it. - -If there is no pre-existing issue or it has been closed, 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. - -### Writing an Issue - -For the subject of an issue, please start it by writing the feature or functionality it relates to, i.e. "Create Account:..." or "Dataset Page:...". In the body of the issue, please outline the issue you are reporting with as much detail as possible. In order for the Dataverse development team to best respond to the issue, we need as much information about the issue as you can provide. Include steps to reproduce bugs. Indicate which version you're using, which is shown at the bottom of the page. We love screenshots! - -### Issue Attachments - -You can attach certain files (images, screenshots, logs, etc.) by dragging and dropping, selecting them, or pasting from the clipboard. Files must be one of GitHub's [supported attachment formats] such as png, gif, jpg, txt, pdf, zip, etc. (Pro tip: A file ending in .log can be renamed to .txt so you can upload it.) If there's no easy way to attach your file, please include a URL that points to the file in question. - -[supported attachment formats]: https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/ - -## Documentation - -The source for the documentation at http://guides.dataverse.org/en/latest/ is in the GitHub repo under the "[doc][]" folder. If you find a typo or inaccuracy or something to clarify, please send us a pull request! For more on the tools used to write docs, please see the [documentation][] section of the Developer Guide. - -[doc]: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source -[documentation]: http://guides.dataverse.org/en/latest/developers/documentation.html - -## Code/Pull Requests - -We love code contributions. Developers are not limited to the main Dataverse code in this git repo. You can help with API client libraries in your favorite language that are mentioned in the [API Guide][] or create a new library. You can help work on configuration management code that's mentioned in the [Installation Guide][]. The Installation Guide also covers a relatively new concept called "external tools" that allows developers to create their own tools that are available from within an installation of Dataverse. - -[API Guide]: http://guides.dataverse.org/en/latest/api -[Installation Guide]: http://guides.dataverse.org/en/latest/installation - -If you are interested in working on the main Dataverse code, great! Before you start coding, please reach out to us either on the [dataverse-community Google Group][], the [dataverse-dev Google Group][], [chat.dataverse.org][], or via support@dataverse.org to make sure the effort is well coordinated and we avoid merge conflicts. We maintain a list of [community contributors][] and [dev efforts][] the community is working on so please let us know if you'd like to be added or removed from either list. - -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. That page also includes tips on making a pull request. - -After making your pull request, your goal should be to help it advance through our kanban board at https://github.com/orgs/IQSS/projects/34 . If no one has moved your pull request to the code review column in a timely manner, please reach out. Note that once a pull request is created for an issue, we'll remove the issue from the board so that we only track one card (the pull request). - -Thanks for your contribution! - -[dataverse-community Google Group]: https://groups.google.com/group/dataverse-community -[Community Call]: https://dataverse.org/community-calls -[dataverse-dev Google Group]: https://groups.google.com/group/dataverse-dev -[community contributors]: https://docs.google.com/spreadsheets/d/1o9DD-MQ0WkrYaEFTD5rF_NtyL8aUISgURsAXSL7Budk/edit?usp=sharing -[dev efforts]: https://github.com/orgs/IQSS/projects/34/views/6 +[Contributor Guide]: https://guides.dataverse.org/en/latest/contributor/index.html diff --git a/doc/release-notes/10531-contrib.md b/doc/release-notes/10531-contrib.md new file mode 100644 index 00000000000..6cfbe988992 --- /dev/null +++ b/doc/release-notes/10531-contrib.md @@ -0,0 +1 @@ +A new [Contributor Guide](https://dataverse-guide--10532.org.readthedocs.build/en/10532/contributor/index.html) has been added by the UX Working Group (#10531 and #10532). diff --git a/doc/sphinx-guides/source/admin/integrations.rst b/doc/sphinx-guides/source/admin/integrations.rst index e48d7a60798..7a9b9c92f77 100644 --- a/doc/sphinx-guides/source/admin/integrations.rst +++ b/doc/sphinx-guides/source/admin/integrations.rst @@ -290,4 +290,4 @@ If you have an idea for an integration, please ask on the `dataverse-community < Many integrations take the form of "external tools". See the :doc:`external-tools` section for details. External tool makers should check out the :doc:`/api/external-tools` section of the API Guide. -Please help us keep this page up to date making a pull request! To get started, see the :doc:`/developers/documentation` section of the Developer Guide. +Please help us keep this page up to date making a pull request! To get started, see the :doc:`/contributor/documentation` section of the Contributor Guide. diff --git a/doc/sphinx-guides/source/api/faq.rst b/doc/sphinx-guides/source/api/faq.rst index 439783779c3..c335b30a0e0 100644 --- a/doc/sphinx-guides/source/api/faq.rst +++ b/doc/sphinx-guides/source/api/faq.rst @@ -82,12 +82,12 @@ The following tasks cannot currently be automated via API because no API exists If you would like APIs for any of the features above, please open a GitHub issue at https://github.com/IQSS/dataverse/issues -You are also welcome to open an issue to add to the list above. Or you are welcome to make a pull request. Please see the :doc:`/developers/documentation` section of the Developer Guide for instructions. +You are also welcome to open an issue to add to the list above. Or you are welcome to make a pull request. Please see the :doc:`/contributor/documentation` section of the Contributor Guide for instructions. Why Are the Return Values (HTTP Status Codes) Not Documented? ------------------------------------------------------------- -They should be. Please consider making a pull request to help. The :doc:`/developers/documentation` section of the Developer Guide should help you get started. :ref:`create-dataverse-api` has an example you can follow or you can come up with a better way. +They should be. Please consider making a pull request to help. The :doc:`/contributor/documentation` section of the Contriburor Guide should help you get started. :ref:`create-dataverse-api` has an example you can follow or you can come up with a better way. Also, please note that we are starting to experiment with putting response codes in our OpenAPI document. See :ref:`openapi`. diff --git a/doc/sphinx-guides/source/contributor/code.md b/doc/sphinx-guides/source/contributor/code.md new file mode 100644 index 00000000000..2a1dec08c05 --- /dev/null +++ b/doc/sphinx-guides/source/contributor/code.md @@ -0,0 +1,58 @@ +# Contributing Code + +We love code contributions! There are lots of ways you can help. + +```{contents} Contents: +:local: +:depth: 3 +``` + +## Finding an Issue to Work On + +New contributors often wonder what issues they should work on first. + +### Many Codebases, Many Languages + +The primary codebase and issue tracker for Dataverse is . It's mostly backend code written in Java. However, there are many other codebases you can work on in a variety of languages. Here are a few that are especially active: + +- (Java) +- (React) +- (TypeScript) +- (Javascript) +- (Python) +- (Ansible) +- (Javascript) + +If nothing above sparks joy, you can find more projects to work on under {doc}`/api/client-libraries`, {doc}`/api/external-tools`, {ref}`related-projects`, and {doc}`/api/apps`. + +### Picking a Good First Issue + +Once you've decided which codebase suits you, you should try to identify an issue to work on. Some codebases use a label like "good first issue" to suggest issues for newcomers. + +For the main codebase, please see {ref}`finding-github-issues-to-work-on` which includes information on labels like "good first issue". + +Other codebases may use different labels. Check the README or other documentation for that codebase. + +If there is a linked pull request that is trying to close the issue, you should probably find another issue. + +If you are having trouble finding an issue or have any questions at all, please do not hesitate to reach out. See {ref}`getting-help-developers`. + +## Making a Pull Request + +For the main codebase, please see {ref}`how-to-make-a-pull-request`. + +For other codebases, consult the README. + +## Reviewing Code + +Reviewing code is a great way to learn about a codebase. For any codebase you can browse open pull requests, of course, but for the primary codebases, you can take a look at the "Ready for Review" and "In Review" columns at . + +You are welcome to review code informally or to leave an actual review. We're interested in what you think. + +## Reproducing Bugs + +At times, bugs are reported that we haven't had time to confirm. You can help out by reproducing bugs and commenting on the issue the results you find. + +## Getting Help + +If you have any questions at all, please do not hesitate to reach out. See {ref}`getting-help-developers`. diff --git a/doc/sphinx-guides/source/contributor/documentation.md b/doc/sphinx-guides/source/contributor/documentation.md new file mode 100644 index 00000000000..12a4266c9ff --- /dev/null +++ b/doc/sphinx-guides/source/contributor/documentation.md @@ -0,0 +1,192 @@ +# Writing Documentation + +Thank you for your interest in contributing documentation to Dataverse! Good documentation is absolutely critical to the success of software. + +```{contents} Contents: +:local: +:depth: 3 +``` + +## Overview + +The Dataverse guides are written using [Sphinx](https://sphinx-doc.org). + +The source files are stored under [doc/sphinx-guides](https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides) in the main "dataverse" repo on GitHub. + +Historically, guides have been written in the default Sphinx format, [reStructuredText][] (.rst), but newer guides such as the {doc}`/contributor/index` are written in [Markdown][] (.md). + +[reStructuredText]: https://en.wikipedia.org/wiki/ReStructuredText +[Markdown]: https://en.wikipedia.org/wiki/Markdown + +Below we'll present a technique for making quick edits to the guides using GitHub's web editor ("quick fix"). We'll also describe how to install Sphinx locally for more significant edits. + +Finally, we'll provide some guidelines on writing content. + +We could use some help on writing this very page and helping newcomers get started. Please don't be shy about suggesting improvements! You can open an issue at , post to , write to the [mailing list](https://groups.google.com/g/dataverse-community), or suggest a change with a pull request. + +## Quick Fix + +If you find a typo or a small error in the documentation you can fix it using GitHub's online web editor. Generally speaking, we will be following [GitHub's guidance on editing files in another user's repository](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository). + +- Navigate to where you will see folders for each of the guides: [admin][], [api][], [container][], etc. +- Find the file you want to edit under one of the folders above. +- Click the pencil icon in the upper-right corner. If this is your first contribution to Dataverse, the hover text over the pencil icon will say "Fork this project and edit this file". +- Make changes to the file and preview them. +- In the **Commit changes** box, enter a description of the changes you have made and click **Propose file change**. +- Under the **Write** tab, delete the long welcome message and write a few words about what you fixed. +- Click **Create Pull Request**. + +That's it! Thank you for your contribution! Your pull request will be added manually to the main Dataverse project board at and will go through code review and QA before it is merged into the "develop" branch. Along the way, developers might suggest changes or make them on your behalf. Once your pull request has been merged you will be listed as a contributor at ! 🎉 + +Please see for an example of a quick fix that was merged (the "Files changed" tab shows how a typo was fixed). + +Preview your documentation changes which will be built automatically as part of your pull request in Github. It will show up as a check entitled: `docs/readthedocs.org:dataverse-guide — Read the Docs build succeeded!`. For example, this PR built to . + +If you would like to read more about the Dataverse's use of GitHub, please see the {doc}`/developers/version-control` section of the Developer Guide. For bug fixes and features we request that you create an issue before making a pull request but this is not at all necessary for quick fixes to the documentation. + +[admin]: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/admin +[api]: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/api +[container]: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/container + +## Building the Guides with Sphinx + +While the "quick fix" technique shown above should work fine for minor changes, especially for larger changes, we recommend installing Sphinx on your computer or using a Sphinx Docker container to build the guides locally so you can get an accurate preview of your changes. + +In case you decide to use a Sphinx Docker container to build the guides, you can skip the next two installation sections, but you will need to have Docker installed. + +### Installing Sphinx + +First, make a fork of https://github.com/IQSS/dataverse and clone your fork locally. Then change to the ``doc/sphinx-guides`` directory. + +``cd doc/sphinx-guides`` + +Create a Python virtual environment, activate it, then install dependencies: + +``python3 -m venv venv`` + +``source venv/bin/activate`` + +``pip install -r requirements.txt`` + +### Installing GraphViz + +In some parts of the documentation, graphs are rendered as images using the Sphinx GraphViz extension. + +Building the guides requires the ``dot`` executable from GraphViz. + +This requires having `GraphViz `_ installed and either having ``dot`` on the path or +`adding options to the make call `_. + +### Editing and Building the Guides + +To edit the existing documentation: + +- Create a branch (see :ref:`how-to-make-a-pull-request`). +- In ``doc/sphinx-guides/source`` you will find the .rst files that correspond to https://guides.dataverse.org. +- Using your preferred text editor, open and edit the necessary files, or create new ones. + +Once you are done, you can preview the changes by building the guides locally. As explained, you can build the guides with Sphinx locally installed, or with a Docker container. + +#### Building the Guides with Sphinx Installed Locally + +Open a terminal, change directories to `doc/sphinx-guides`, activate (or reactivate) your Python virtual environment, and build the guides. + +`cd doc/sphinx-guides` + +`source venv/bin/activate` + +`make clean` + +`make html` + +#### Building the Guides with a Sphinx Docker Container and a Makefile + +We have added a Makefile to simplify the process of building the guides using a Docker container, you can use the following commands from the repository root: + +- `make docs-html` +- `make docs-pdf` +- `make docs-epub` +- `make docs-all` + +#### Building the Guides with a Sphinx Docker Container and CLI + +If you want to build the guides using a Docker container, execute the following command in the repository root: + +`docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:7.2.6 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make html"` + +#### Previewing the Guides + +After Sphinx is done processing the files you should notice that the `html` folder in `doc/sphinx-guides/build` directory has been updated. You can click on the files in the `html` folder to preview the changes. + +Now you can make a commit with the changes to your own fork in GitHub and submit a pull request. See {ref}`how-to-make-a-pull-request`. + +## Writing Guidelines + +### Writing Style Guidelines + +Please observe the following when writing documentation: + +- Use American English spelling. +- Use examples when possible. +- Break up longer paragraphs. +- Use "double quotes" instead of 'single quotes'. +- Favor "and" (data and code) over slashes (data/code). + +### Table of Contents + +Every non-index page should use the following code to display a table of contents of internal sub-headings. This code should be placed below any introductory text and directly above the first subheading, much like a Wikipedia page. + +If the page is written in reStructuredText (.rst), use this form: + + .. contents:: |toctitle| + :local: + +If the page is written in Markdown (.md), use this form: + + ```{contents} Contents: + :local: + :depth: 3 + ``` + +### Images + +A good documentation is just like a website enhanced and upgraded by adding high quality and self-explanatory images. Often images depict a lot of written text in a simple manner. Within our Sphinx docs, you can add them in two ways: a) add a PNG image directly and include or b) use inline description languages like GraphViz (current only option). + +While PNGs in the git repo can be linked directly via URL, Sphinx-generated images do not need a manual step and might provide higher visual quality. Especially in terms of quality of content, generated images can be extendend and improved by a textbased and reviewable commit, without needing raw data or source files and no diff around. + +### Cross References + +When adding ReStructured Text (.rst) [cross references](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role), use the hyphen character (`-`) as the word separator for the cross reference label. For example, `my-reference-label` would be the preferred label for a cross reference as opposed to, for example, `my_reference_label`. + +## PDF Version of the Guides + +The HTML version of the guides is the official one. Any other formats are maintained on a best effort basis. + +If you would like to build a PDF version of the guides and have Docker installed, please try the command below from the root of the git repo: + +`docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx-latexpdf:7.2.6 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make latexpdf LATEXMKOPTS=\"-interaction=nonstopmode\"; cd ../.. && ls -1 doc/sphinx-guides/build/latex/Dataverse.pdf"` + +A few notes about the command above: + +- Hopefully the PDF was created at `doc/sphinx-guides/build/latex/Dataverse.pdf`. +- For now, we are using "nonstopmode" but this masks some errors. +- See requirements.txt for a note regarding the version of Sphinx we are using. + +Also, as of this writing we have enabled PDF builds from the "develop" branch. You download the PDF from + +If you would like to help improve the PDF version of the guides, please get in touch! Please see {ref}`getting-help-developers` for ways to contact the developer community. + + +## Hosting Your Own Version of the Guides + +Some installations of Dataverse maintain their own versions of the guides and use settings like {ref}`:NavbarGuidesUrl` or {ref}`:GuidesBaseUrl` to point their users to them. + +### Having Google Index the Latest Version + +As each version of the Dataverse software is released, there is an updated version of the guides released with it. Google and other search engines index all versions, which may confuse users who discover your guides in the search results as to which version they should be looking at. When learning about your installation from the search results, it is best to be viewing the *latest* version. + +In order to make it clear to the crawlers that we only want the latest version discoverable in their search results, we suggest adding this to your `robots.txt` file: + + User-agent: * + Allow: /en/latest/ + Disallow: /en/ diff --git a/doc/sphinx-guides/source/contributor/index.md b/doc/sphinx-guides/source/contributor/index.md new file mode 100644 index 00000000000..e75cc58bccd --- /dev/null +++ b/doc/sphinx-guides/source/contributor/index.md @@ -0,0 +1,105 @@ +# Contributor Guide + +Thank you for your interest in contributing to Dataverse! We are open to contributions from everyone. We welcome contributions of ideas, bug reports, documentation, code, and more! + +```{contents} Contents: +:local: +:depth: 3 +``` + +## Ideas and Feature Requests + +We would love to hear your ideas!💡 + +1. Please check if your idea or feature request is already captured in our [issue tracker][] or [roadmap][]. +1. Bring your idea to the community by posting on our [Google Group][] or [chat.dataverse.org][]. +1. To discuss privately, email us at . + +[issue tracker]: https://github.com/IQSS/dataverse/issues +[roadmap]: https://www.iq.harvard.edu/roadmap-dataverse-project +[chat.dataverse.org]: http://chat.dataverse.org +[Google Group]: https://groups.google.com/group/dataverse-community + +## Bug Reports + +Before submitting an issue, please search for existing issues in our [issue tracker][]. If there is an existing open issue that matches the issue you want to report, please add a comment to it or give it a 👍 (thumbs up). + +If there is no pre-existing issue or it has been closed, please open a new issue (unless it is a security issue which should be reported privately to as discussed under {ref}`reporting-security-issues` in the Installation Guide). + +If you do not receive a reply to your new issue or comment in a timely manner, please ping us at [chat.dataverse.org][]. + +## Documentation + +Documentation is such a large topic (and important!) that we have a dedicate section on it: + +```{toctree} +:maxdepth: 1 +documentation.md +``` + +## Translations + +If you speak multiple languages, you are very welcome to help us translate Dataverse! Please see {ref}`help-translate` for details. + +## Code + +Dataverse is open source and we love code contributions. Developers are not limited to the main Dataverse code in this git repo. We have projects in C, C++, Go, Java, Javascript, Julia, PHP, Python, R, Ruby, TypeScript and more. To get started, please see the following pages: + +```{toctree} +:maxdepth: 1 +code.md +``` + +## Usability Testing + +Please email us at or fill in our [feedback form][] if you are interested in participating in usability testing. + +[feedback form]: https://goo.gl/forms/p7uu3GfiWYSlJrsi1 + +## Answering Questions + +People come along with questions on the [mailing list](https://groups.google.com/g/dataverse-community) and in [chat][] all the time. You are very welcome to help out by answering these questions to the best of your ability. + +[chat]: https://chat.dataverse.org + +## Sample Data + +Consider contributing to , a git repo of realistic-looking data that is used for testing. + +## Issue Triage + +New issues come in all the time, especially for the main issue tracker at . + +You can help by leaving comments. You can mention related issues or answer questions. + +If you are interested in adding issue labels or related curation, please get in touch! + +## Giving Talks + +If you give a recorded talk about Dataverse, we are happy to add it to [DataverseTV](https://dataverse.org/dataversetv). You can just leave a comment on the [spreadsheet](https://docs.google.com/spreadsheets/d/1uVk_57Ek_A49sLZ5OKdI6QASKloWNzykni3kcYNzpxA/edit#gid=0) or make some noise in [chat][]. + +For non-recorded talks, we are happy to upload your slides to . Please email . + +## Working Groups + +Most working groups are wide open to participation. For the current list of groups, please see . + +You're welcome to start your own working group, of course. We can help you get the word out. + +## GDCC + +The popularity of the Dataverse software has resulted in a continuously growing community with different needs and requirements. The Global Dataverse Community Consortium (GDCC) helps coordinate community efforts and sustain the software and community in the long term. Please consider contributing to GDCC by joining as an institutional member (). + +## Artwork + +Surely we can put artistic talent to use. A contributor [drew cartoon animals chatting about Dataverse](https://github.com/IQSS/chat.dataverse.org/issues/18), for example. + +As [annnounced](https://groups.google.com/g/dataverse-community/c/pM39_9O5Rug/m/CK-gJqZFBgAJ), we have a [sticker template](https://dataverse.org/sites/projects.iq.harvard.edu/files/dataverseorg/files/dataverse_community_stickers_template.zip) you can use. + +See [Illustrations from The Turing Way](https://zenodo.org/doi/10.5281/zenodo.3332807) for how that community has created artwork. Perhaps we can create a similar collection. + +## Other Contributions + +We consulted but no list is comprehensive. + +What else should we list here? How to YOU want to contribute to Dataverse? 🎉 diff --git a/doc/sphinx-guides/source/developers/documentation.rst b/doc/sphinx-guides/source/developers/documentation.rst deleted file mode 100755 index 5ec74249f4d..00000000000 --- a/doc/sphinx-guides/source/developers/documentation.rst +++ /dev/null @@ -1,172 +0,0 @@ -===================== -Writing Documentation -===================== - -.. contents:: |toctitle| - :local: - -Quick Fix ------------ - -If you find a typo or a small error in the documentation you can fix it using GitHub's online web editor. Generally speaking, we will be following https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository - -- Navigate to https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source where you will see folders for each of the guides: `admin`_, `api`_, `developers`_, `installation`_, `style`_, `user`_. -- Find the file you want to edit under one of the folders above. -- Click the pencil icon in the upper-right corner. If this is your first contribution to the Dataverse Project, the hover text over the pencil icon will say "Fork this project and edit this file". -- Make changes to the file and preview them. -- In the **Commit changes** box, enter a description of the changes you have made and click **Propose file change**. -- Under the **Write** tab, delete the long welcome message and write a few words about what you fixed. -- Click **Create Pull Request**. - -That's it! Thank you for your contribution! Your pull request will be added manually to the main Dataverse Project board at https://github.com/orgs/IQSS/projects/34 and will go through code review and QA before it is merged into the "develop" branch. Along the way, developers might suggest changes or make them on your behalf. Once your pull request has been merged you will be listed as a contributor at https://github.com/IQSS/dataverse/graphs/contributors - -Please see https://github.com/IQSS/dataverse/pull/5857 for an example of a quick fix that was merged (the "Files changed" tab shows how a typo was fixed). - -Preview your documentation changes which will be built automatically as part of your pull request in Github. It will show up as a check entitled: `docs/readthedocs.org:dataverse-guide — Read the Docs build succeeded!`. For example, this PR built to https://dataverse-guide--9249.org.readthedocs.build/en/9249/. - -If you would like to read more about the Dataverse Project's use of GitHub, please see the :doc:`version-control` section. For bug fixes and features we request that you create an issue before making a pull request but this is not at all necessary for quick fixes to the documentation. - -.. _admin: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/admin -.. _api: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/api -.. _developers: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/developers -.. _installation: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/installation -.. _style: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/style -.. _user: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/user - -Building the Guides with Sphinx -------------------------------- - -The Dataverse guides are written using Sphinx (https://sphinx-doc.org). We recommend installing Sphinx on your localhost or using a Sphinx Docker container to build the guides locally so you can get an accurate preview of your changes. - -In case you decide to use a Sphinx Docker container to build the guides, you can skip the next two installation sections, but you will need to have Docker installed. - -Installing Sphinx -~~~~~~~~~~~~~~~~~ - -First, make a fork of https://github.com/IQSS/dataverse and clone your fork locally. Then change to the ``doc/sphinx-guides`` directory. - -``cd doc/sphinx-guides`` - -Create a Python virtual environment, activate it, then install dependencies: - -``python3 -m venv venv`` - -``source venv/bin/activate`` - -``pip install -r requirements.txt`` - -Installing GraphViz -~~~~~~~~~~~~~~~~~~~ - -In some parts of the documentation, graphs are rendered as images using the Sphinx GraphViz extension. - -Building the guides requires the ``dot`` executable from GraphViz. - -This requires having `GraphViz `_ installed and either having ``dot`` on the path or -`adding options to the make call `_. - -Editing and Building the Guides -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To edit the existing documentation: - -- Create a branch (see :ref:`how-to-make-a-pull-request`). -- In ``doc/sphinx-guides/source`` you will find the .rst files that correspond to https://guides.dataverse.org. -- Using your preferred text editor, open and edit the necessary files, or create new ones. - -Once you are done, you can preview the changes by building the guides locally. As explained, you can build the guides with Sphinx locally installed, or with a Docker container. - -Building the Guides with Sphinx Locally Installed -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Open a terminal, change directories to ``doc/sphinx-guides``, activate (or reactivate) your Python virtual environment, and build the guides. - -``cd doc/sphinx-guides`` - -``source venv/bin/activate`` - -``make clean`` - -``make html`` - -Building the Guides with a Sphinx Docker Container -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Building with Docker and Makefile:** - -We have added a Makefile to simplify the process of building the guides using a Docker container, you can use some of the following from the repository root: - -- `make docs-html` -- `make docs-pdf` -- `make docs-epub` -- `make docs-all` - -**Building with Docker and CLI:** - -If you want to build the guides using a Docker container, execute the following command in the repository root: - -``docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:7.2.6 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make html"`` - -Previewing the Guides -^^^^^^^^^^^^^^^^^^^^^ - -After Sphinx is done processing the files you should notice that the ``html`` folder in ``doc/sphinx-guides/build`` directory has been updated. -You can click on the files in the ``html`` folder to preview the changes. - -Now you can make a commit with the changes to your own fork in GitHub and submit a pull request. See :ref:`how-to-make-a-pull-request`. - -Table of Contents ------------------ - -Every non-index page should use the following code to display a table of contents of internal sub-headings: :: - - .. contents:: |toctitle| - :local: - -This code should be placed below any introductory text/images and directly above the first subheading, much like a Wikipedia page. - -Images ------- - -A good documentation is just like a website enhanced and upgraded by adding high quality and self-explanatory images. -Often images depict a lot of written text in a simple manner. Within our Sphinx docs, you can add them in two ways: a) add a -PNG image directly and include or b) use inline description languages like GraphViz (current only option). - -While PNGs in the git repo can be linked directly via URL, Sphinx-generated images do not need a manual step and might -provide higher visual quality. Especially in terms of quality of content, generated images can be extendend and improved -by a textbased and reviewable commit, without needing raw data or source files and no diff around. - -Cross References ----------------- - -**NOTE:** When adding ReStructured Text (RST) `cross references `_, use the hyphen character (``-``) as the word separator for the cross reference label. For example, ``my-reference-label`` would be the preferred label for a cross reference as opposed to, for example, ``my_reference_label``. - -Versions --------- - -For installations hosting their own copies of the guides, note that as each version of the Dataverse Software is released, there is an updated version of the guides released with it. Google and other search engines index all versions, which may confuse users who discover your guides in the search results as to which version they should be looking at. When learning about your installation from the search results, it is best to be viewing the *latest* version. - -In order to make it clear to the crawlers that we only want the latest version discoverable in their search results, we suggest adding this to your ``robots.txt`` file:: - - User-agent: * - Allow: /en/latest/ - Disallow: /en/ - -PDF Version of the Guides -------------------------- - -The HTML version of the guides is the official one. Any other formats are maintained on a best effort basis. - -If you would like to build a PDF version of the guides and have Docker installed, please try the command below from the root of the git repo: - -``docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx-latexpdf:7.2.6 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make latexpdf LATEXMKOPTS=\"-interaction=nonstopmode\"; cd ../.. && ls -1 doc/sphinx-guides/build/latex/Dataverse.pdf"`` - -A few notes about the command above: - -- Hopefully the PDF was created at ``doc/sphinx-guides/build/latex/Dataverse.pdf``. -- For now, we are using "nonstopmode" but this masks some errors. -- See requirements.txt for a note regarding the version of Sphinx we are using. - -Also, as of this writing we have enabled PDF builds from the "develop" branch. You download the PDF from http://preview.guides.gdcc.io/_/downloads/en/develop/pdf/ - -If you would like to help improve the PDF version of the guides, please get in touch! Please see :ref:`getting-help-developers` for ways to contact the developer community. diff --git a/doc/sphinx-guides/source/developers/index.rst b/doc/sphinx-guides/source/developers/index.rst index 25fea138736..6d01e13d78e 100755 --- a/doc/sphinx-guides/source/developers/index.rst +++ b/doc/sphinx-guides/source/developers/index.rst @@ -18,7 +18,6 @@ Developer Guide version-control sql-upgrade-scripts testing - documentation api-design security performance diff --git a/doc/sphinx-guides/source/developers/intro.rst b/doc/sphinx-guides/source/developers/intro.rst index 350968012d8..0e74dc1c36f 100755 --- a/doc/sphinx-guides/source/developers/intro.rst +++ b/doc/sphinx-guides/source/developers/intro.rst @@ -2,7 +2,7 @@ Introduction ============ -Welcome! `The Dataverse Project `_ is an `open source `_ project that loves `contributors `_! +Welcome! `The Dataverse Project `_ is an `open source `_ project that loves contributors! .. contents:: |toctitle| :local: @@ -10,7 +10,7 @@ Welcome! `The Dataverse Project `_ is an `open source `_ mailing list, `community calls `_, or support@dataverse.org. +If you have any questions at all, please reach out to other developers via https://chat.dataverse.org, the `dataverse-dev `_ mailing list, the `dataverse-community `_ mailing list, or `community calls `_. .. _core-technologies: Core Technologies ----------------- -The Dataverse Software is a `Jakarta EE `_ application that is compiled into a WAR file and deployed to an application server (app server) which is configured to work with a relational database (PostgreSQL) and a search engine (Solr). +Dataverse is a `Jakarta EE `_ application that is compiled into a WAR file and deployed to an application server (app server) which is configured to work with a relational database (PostgreSQL) and a search engine (Solr). -We make use of a variety of Jakarta EE technologies such as JPA, JAX-RS, JMS, and JSF. The front end is built using PrimeFaces and Bootstrap. +We make use of a variety of Jakarta EE technologies such as JPA, JAX-RS, JMS, and JSF. In addition, we use parts of Eclipse MicroProfile such as `MicroProfile Config `_. -In addition, we start to adopt parts of Eclipse MicroProfile, namely `MicroProfile Config `_. +The frontend is built using PrimeFaces and Bootstrap. A new frontend is being built using React at https://github.com/IQSS/dataverse-frontend Roadmap ------- -For the Dataverse Software development roadmap, please see https://www.iq.harvard.edu/roadmap-dataverse-project +For the roadmap, please see https://www.iq.harvard.edu/roadmap-dataverse-project .. _kanban-board: @@ -47,20 +47,26 @@ You can get a sense of what's currently in flight (in dev, in QA, etc.) by looki Issue Tracker ------------- -We use GitHub Issues as our issue tracker: https://github.com/IQSS/dataverse/issues +The main issue tracker is https://github.com/IQSS/dataverse/issues but note that individual projects have their own issue trackers. Related Guides -------------- -If you are a developer who wants to make use of the Dataverse Software APIs, please see the :doc:`/api/index`. If you have front-end UI questions, please see the :doc:`/style/index`. +If you are wondering about how to contribute generally, please see the :doc:`/contributor/index`. -If you are a sysadmin who likes to code, you may be interested in hacking on installation scripts mentioned in the :doc:`/installation/index`. +If you are a developer who wants to make use of the Dataverse APIs, please see the :doc:`/api/index`. + +If you have frontend UI questions, please see the :doc:`/style/index`. For the new frontend, see https://github.com/IQSS/dataverse-frontend If you are a Docker enthusiasts, please check out the :doc:`/container/index`. +.. _related-projects: + Related Projects ---------------- +Note: this list is somewhat old. Please see also the :doc:`/contributor/code` section of the Contributor Guide. + As a developer, you also may be interested in these projects related to Dataverse: - External Tools - add additional features to the Dataverse Software without modifying the core: :doc:`/api/external-tools` diff --git a/doc/sphinx-guides/source/developers/version-control.rst b/doc/sphinx-guides/source/developers/version-control.rst index 07922b56b86..8648c8ce2a0 100644 --- a/doc/sphinx-guides/source/developers/version-control.rst +++ b/doc/sphinx-guides/source/developers/version-control.rst @@ -69,6 +69,8 @@ Find or Create a GitHub Issue An issue represents a bug (unexpected behavior) or a new feature in Dataverse. We'll use the issue number in the branch we create for our pull request. +.. _finding-github-issues-to-work-on: + Finding GitHub Issues to Work On ******************************** diff --git a/doc/sphinx-guides/source/index.rst b/doc/sphinx-guides/source/index.rst index 3184160b387..af394108eea 100755 --- a/doc/sphinx-guides/source/index.rst +++ b/doc/sphinx-guides/source/index.rst @@ -17,6 +17,7 @@ These documentation guides are for the |version| version of Dataverse. To find g admin/index api/index installation/index + contributor/index developers/index container/index style/index diff --git a/doc/sphinx-guides/source/installation/config.rst b/doc/sphinx-guides/source/installation/config.rst index d07bc098e2e..9e4a5e0ee7b 100644 --- a/doc/sphinx-guides/source/installation/config.rst +++ b/doc/sphinx-guides/source/installation/config.rst @@ -1741,6 +1741,8 @@ Now that you have a "languages.zip" file, you can load it into your Dataverse in Click on the languages using the drop down in the header to try them out. +.. _help-translate: + How to Help Translate the Dataverse Software Into Your Language +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -3731,7 +3733,7 @@ Note: by default, the URL is composed from the settings ``:GuidesBaseUrl`` and ` :GuidesBaseUrl ++++++++++++++ -Set ``:GuidesBaseUrl`` to override the default value "https://guides.dataverse.org". If you are interested in writing your own version of the guides, you may find the :doc:`/developers/documentation` section of the Developer Guide helpful. +Set ``:GuidesBaseUrl`` to override the default value "https://guides.dataverse.org". If you are interested in writing your own version of the guides, you may find the :doc:`/contributor/documentation` section of the Contributor Guide helpful. ``curl -X PUT -d http://dataverse.example.edu http://localhost:8080/api/admin/settings/:GuidesBaseUrl`` diff --git a/doc/sphinx-guides/source/installation/intro.rst b/doc/sphinx-guides/source/installation/intro.rst index 6d77a1209b2..1c239863e98 100644 --- a/doc/sphinx-guides/source/installation/intro.rst +++ b/doc/sphinx-guides/source/installation/intro.rst @@ -53,6 +53,6 @@ If you've encountered a problem installing Dataverse and are ready to ask for he Improving this Guide -------------------- -If you spot a typo in this guide or would like to suggest an improvement, please find the appropriate file in https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/installation and send a pull request as explained in the :doc:`/developers/documentation` section of the Developer Guide. You are also welcome to simply open an issue at https://github.com/IQSS/dataverse/issues to describe the problem with this guide. +If you spot a typo in this guide or would like to suggest an improvement, please find the appropriate file in https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/installation and send a pull request as explained in the :doc:`/contributor/documentation` section of the Contributor Guide. You are also welcome to simply open an issue at https://github.com/IQSS/dataverse/issues to describe the problem with this guide. Next is the :doc:`prep` section. diff --git a/doc/sphinx-guides/source/qa/testing-infrastructure.md b/doc/sphinx-guides/source/qa/testing-infrastructure.md index 804e4c0afe6..6ec26c6da49 100644 --- a/doc/sphinx-guides/source/qa/testing-infrastructure.md +++ b/doc/sphinx-guides/source/qa/testing-infrastructure.md @@ -39,7 +39,7 @@ To build and test a PR, we use a job called `IQSS_Dataverse_Internal` on . This Read the Docs preview is also mentioned under also {doc}`/developers/documentation`. +Note that changes to guides can also be previewed on Read the Docs. In the pull request, look for a link like . This Read the Docs preview is also mentioned under also {doc}`/contributor/documentation`. ## Other Servers diff --git a/doc/sphinx-guides/source/versions.rst b/doc/sphinx-guides/source/versions.rst index d76f9a889cb..850702d823e 100755 --- a/doc/sphinx-guides/source/versions.rst +++ b/doc/sphinx-guides/source/versions.rst @@ -6,7 +6,7 @@ Dataverse Software Documentation Versions This list provides a way to refer to the documentation for previous and future versions of the Dataverse Software. In order to learn more about the updates delivered from one version to another, visit the `Releases `__ page in our GitHub repo. -- pre-release `HTML (not final!) `__ and `PDF (experimental!) `__ built from the :doc:`develop ` branch :doc:`(how to contribute!) ` +- pre-release `HTML (not final!) `__ and `PDF (experimental!) `__ built from the :doc:`develop ` branch :doc:`(how to contribute!) ` - 6.2 - `6.1 `__ - `6.0 `__