Skip to content

Commit

Permalink
Merge pull request #266 from geoblacklight/contribution-guide
Browse files Browse the repository at this point in the history 
Add contribution guide for the website repo
  • Loading branch information
@karenmajewicz
karenmajewicz authored Aug 7, 2024
2 parents 0f4ffa4 + e4c5aeb commit 6d1cee9
Show file tree
Hide file tree
Showing 2 changed files with 102 additions and 86 deletions.
100 changes: 100 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# GeoBlacklight Website Contribution Guide
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).

### Who can contribute?
**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.

## Reporting an issue
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).

- Make sure you have a [GitHub account](https://github.com/)
- Submit a [GitHub issue](./issues) by:
- Clearly describing the issue
- Provide a descriptive summary
- Explain the expected behavior
- Explain the actual behavior
- Provide steps to reproduce the actual behavior

## Contributing to the website or documentation
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.

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.

### Pull Request overview

**Contributors:**

1. Clone or fork the geoblacklight.github.io repository
1. Create a new branch and publish it
1. Make changes to the website files
1. Optionally, preview the site with MkDocs
1. Commit your changes
1. Push to the new branch
1. Open a Pull Request to the **main** branch
1. Add Geoblacklight-Developers as a requested reviewer

**Reviewers:**

1. Review the Pull Request and merge changes to the **main** branch
1. GitHub Actions will automatically push the changes to the gh-pages branch


### Previewing changes in Material for MkDocs

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.

1. Open the Terminal and type the following command to install the MkDocs modules and Material theme.

```
pip install mkdocs-material
```

1. Install the required plugins:

```
pip install mkdocs-table-reader-plugin
pip install mkdocs-git-revision-date-localized-plugin
```


1. Clone or fork the geoblacklight.github.io repository.
1. Create a new branch and publish it.
1. Change into the geoblacklight.github.io directory and type:

```
mkdocs serve
```

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:

```
INFO - Documentation built in 4.15 seconds
INFO - [14:43:24] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [14:43:24] Serving on http://127.0.0.1:8000/
INFO - [14:43:31] Browser connected: http://127.0.0.1:8000/
```

1. In a browser, open the locally hosted site at http://127.0.0.1:8000/ (or whatever address your Terminal shows).
1. Edit the website files and preview them in your browser.
1. When you are ready to publish the changes, commit them locally using GitHub Desktop or a Terminal command.
1. Push to the new branch.
1. Open a Pull Request to the Main branch.
1. Add Geoblacklight-Developers as a requested reviewer.

### Updating d2 diagrams

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:

```
d2 geoblacklight-structure.d2 geoblacklight-structure.png --sketch --pad=50
```

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/).

## Merging a Pull Request

- Please do not merge your own Pull Request - this is considered "poor form."
- 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.
- If you like the Pull Request but want others to chime in, create a +1 comment and tag a user.

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].
88 changes: 2 additions & 86 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This site provides the public-facing website for the GeoBlacklight community.
[GitHub Pages](https://pages.github.com) is a free static site hosting service offered by GitHub.


## GitHub Repository organization:
## Repository organization

### Main branch

Expand Down Expand Up @@ -61,88 +61,4 @@ This is the published branch containing the HTML code for the site. (We do **not

## Updating the GeoBlacklight website

Since this site is edited with Markdown, the minimum requirement to contribute is to just edit or submit new Markdown files. However, MkDocs is relatively simple to install and run locally. This allows you to preview changes locally before submitting them.

To get started, 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/) and for reference.

### Install Material for MkDocs

1. Open the Terminal and type the following:

`pip install mkdocs-material`

This command will install all the necessary modules for the mkdocs platform and the Material theme together.

2. Install the plugins

`pip install mkdocs-table-reader-plugin`

`pip install mkdocs-git-revision-date-localized-plugin`



### Edit the website

1. Clone or fork the geoblacklight.github.io repository

2. Make a new branch

3. Change into the geoblacklight.github.io directory and type:

`mkdocs serve`

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:

```
INFO - Documentation built in 4.15 seconds

INFO - [14:43:24] Watching paths for changes: 'docs', 'mkdocs.yml'

INFO - [14:43:24] Serving on http://127.0.0.1:8000/

INFO - [14:43:31] Browser connected: http://127.0.0.1:8000/
```
4. In a browser, open the locally hosted site at http://127.0.0.1:8000/ (or whatever your Terminal shows)

5. Edit the markdown files and preview them in your browser.

6. When you are ready to publish the changes, commit them locally using GitHub Desktop or a Terminal command.

7. Publish the branch and open a pull request to the Main branch.


### Workflow steps overview

**Contributor:**

1. Clone or update your local instance of the geoblacklight.github.io repository
2. Make a new branch and switch to it
3. Edit the Markdown files
4. Preview the site locally using `mkdocs serve`
5. Commit your changes
6. Publish your branch
7. Open a Pull Request to the main branch

**Publisher:**

1. Accept Pull Request and merge changes to the main branch
2. GitHub Actions will automatically push the changes to the gh-pages branch


Questions about this repository or other elements of GeoBlacklight?

Submit application related issues here: https://github.com/geoblacklight/geoblacklight/issues

Report bugs and typos on the website itself here: https://github.com/geoblacklight/geoblacklight.github.io/issues

### Updating d2 diagrams

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:

```
d2 geoblacklight-structure.d2 geoblacklight-structure.png --sketch --pad=50
```

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/).
Everyone is welcome to contribute to the GeoBlacklight website and our documentation pages. See our [Contribution Guide](https://github.com/geoblacklight/geoblacklight.github.io/blob/main/CONTRIBUTING.md) for detailed information about how to contribute.

0 comments on commit 6d1cee9

Please sign in to comment.