|
| 1 | +# GeoBlacklight Website Contribution Guide |
| 2 | +GeoBlacklight is a collaborative open-source project that :sparkles:welcomes:sparkles: community contributions. To contribute to the GeoBlacklight software codebase, see the [GeoBlacklight Contribution Guide](https://github.com/geoblacklight/geoblacklight/blob/main/CONTRIBUTING.md). |
| 3 | + |
| 4 | +### Who can contribute? |
| 5 | +**Anyone** is welcome to contribute to the GeoBlacklight website and documentation. We follow a set of contribution practices to maintain a technically sustainable and stable software project for everyone. |
| 6 | + |
| 7 | +## Reporting an issue |
| 8 | +Did you find an error on the GeoBlacklight website or documentation pages? You can add an issue for it in the [issue tracker](https://github.com/geoblacklight/geoblacklight.github.io/issues). |
| 9 | + |
| 10 | + - Make sure you have a [GitHub account](https://github.com/) |
| 11 | + - Submit a [GitHub issue](./issues) by: |
| 12 | + - Clearly describing the issue |
| 13 | + - Provide a descriptive summary |
| 14 | + - Explain the expected behavior |
| 15 | + - Explain the actual behavior |
| 16 | + - Provide steps to reproduce the actual behavior |
| 17 | + |
| 18 | +## Contributing to the website or documentation |
| 19 | +We welcome contributions that improve the website and documentation pages. You do *not* need to be a "GeoBlacklight Committer" to contribute code or documentation. We follow the [pull request](https://help.github.com/articles/using-pull-requests/) model for contributing on GitHub. |
| 20 | + |
| 21 | +Since this website is edited with Markdown, the easiest way to contribute is to edit or submit new Markdown files. You can also preview changes locally before submitting them with MkDocs, which is relatively simple to install and run locally. |
| 22 | + |
| 23 | +### Pull Request overview |
| 24 | + |
| 25 | +**Contributors:** |
| 26 | + |
| 27 | +1. Clone or fork the geoblacklight.github.io repository |
| 28 | +1. Create a new branch and publish it |
| 29 | +1. Make changes to the website files |
| 30 | +1. Optionally, preview the site with MkDocs |
| 31 | +1. Commit your changes |
| 32 | +1. Push to the new branch |
| 33 | +1. Open a Pull Request to the **main** branch |
| 34 | +1. Add Geoblacklight-Developers as a requested reviewer |
| 35 | + |
| 36 | +**Reviewers:** |
| 37 | + |
| 38 | +1. Review the Pull Request and merge changes to the **main** branch |
| 39 | +1. GitHub Actions will automatically push the changes to the gh-pages branch |
| 40 | + |
| 41 | + |
| 42 | +### Previewing changes in Material for MkDocs |
| 43 | + |
| 44 | +If you want to preview changes before committing them, follow the steps below. It may also be helpful to visit the [Material for MkDocs Getting Started page](https://squidfunk.github.io/mkdocs-material/getting-started/) for more information. |
| 45 | + |
| 46 | +1. Open the Terminal and type the following command to install the MkDocs modules and Material theme. |
| 47 | + |
| 48 | + ``` |
| 49 | + pip install mkdocs-material |
| 50 | + ``` |
| 51 | + |
| 52 | +1. Install the required plugins: |
| 53 | + |
| 54 | + ``` |
| 55 | + pip install mkdocs-table-reader-plugin |
| 56 | + pip install mkdocs-git-revision-date-localized-plugin |
| 57 | + ``` |
| 58 | + |
| 59 | + |
| 60 | +1. Clone or fork the geoblacklight.github.io repository. |
| 61 | +1. Create a new branch and publish it. |
| 62 | +1. Change into the geoblacklight.github.io directory and type: |
| 63 | + |
| 64 | + ``` |
| 65 | + mkdocs serve |
| 66 | + ``` |
| 67 | + |
| 68 | + This will start a local server so you can preview the site as you build it. You will see text in the Terminal that looks something like this: |
| 69 | + |
| 70 | + ``` |
| 71 | + INFO - Documentation built in 4.15 seconds |
| 72 | + INFO - [14:43:24] Watching paths for changes: 'docs', 'mkdocs.yml' |
| 73 | + INFO - [14:43:24] Serving on http://127.0.0.1:8000/ |
| 74 | + INFO - [14:43:31] Browser connected: http://127.0.0.1:8000/ |
| 75 | + ``` |
| 76 | + |
| 77 | +1. In a browser, open the locally hosted site at http://127.0.0.1:8000/ (or whatever address your Terminal shows). |
| 78 | +1. Edit the website files and preview them in your browser. |
| 79 | +1. When you are ready to publish the changes, commit them locally using GitHub Desktop or a Terminal command. |
| 80 | +1. Push to the new branch. |
| 81 | +1. Open a Pull Request to the Main branch. |
| 82 | +1. Add Geoblacklight-Developers as a requested reviewer. |
| 83 | + |
| 84 | +### Updating d2 diagrams |
| 85 | + |
| 86 | +For any diagrams created with [terrastruct/d2](https://github.com/terrastruct/d2), you can edit the appropriate .d2 file and then generate the diagram image with the following command: |
| 87 | + |
| 88 | + ``` |
| 89 | + d2 geoblacklight-structure.d2 geoblacklight-structure.png --sketch --pad=50 |
| 90 | + ``` |
| 91 | + |
| 92 | +Add the `-w` flag to open a preview and automatically re-generate the diagram as you workon the .d2 file. For more info, see the [d2 documentation](https://d2lang.com/tour/intro/). |
| 93 | + |
| 94 | +## Merging a Pull Request |
| 95 | + |
| 96 | +- Please do not merge your own Pull Request - this is considered "poor form." |
| 97 | +- If you are uncertain about an element of your Pull Request, you can bring other contributors into the conversation by creating a comment that includes their @username. |
| 98 | +- If you like the Pull Request but want others to chime in, create a +1 comment and tag a user. |
| 99 | + |
| 100 | +If you have questions or want to get more involved, join [GeoBlacklight Slack ](https://geoblacklight.slack.com/join/shared_invite/zt-1p7dcay40-Ye_WTt5_iCqU8rDjzhkoWw#/shared-invite/email) or email the [GeoBlacklight Community ](https://groups.google.com/g/geoblacklight-community) at [email protected]. |
0 commit comments