@ -6,19 +6,57 @@ This repository contains website source code for https://almalinux.org.
This website is built with the [Hugo](https://gohugo.io/) web framework.
## For developers
## Contributing
To deploy local development environment, you will need following dependencies installed
on your development host:
We welcome contributions to the website in the form of website updates and design improvements, as well as translations. We've provided specific instructions on how to contribute for each part of the website.
- Blog content, please see [Contributing - Blog Posts](https://github.com/AlmaLinux/almalinux.org/blob/master/contributing-blog-posts.md)
- Help with our Hugo implementation or design improvements, please see [Contributing - Code and Design](#contributing-code-and-design)
- To help with translations, please see [Contributing - Translations](#localization-and-translation)
## Contributing - Code and Design
All of the development of the AlmaLinux website is done through this repo on GitHub.
### Reporting a Bug
Good bug reports can be very helpful. A bug is a demonstrable problem with the code or functionality.
Please use the [GitHub issues](https://github.com/AlmaLinux/almalinux.org/issues) and check if the issue has already been reported. A good bug report should be as detailed as possible, so that others won't have to follow up for the essential details.
### Requesting a Feature
1. [Search the issues](https://github.com/AlmaLinux/almalinux.org/issues) for any open requests for the same feature, and give a thumbs up or +1 on existing requests.
1. If no previous requests exist, create a new issue. Please be as clear as possible about why the feature is needed and the intended use case.
### Contributing code or design edits
If you plan to propose code changes, please first confirm that there are no open issues or pull requests that match your proposal, and then open an [issue](https://github.com/AlmaLinux/almalinux.org/issues) with a brief proposal and discuss it with the Marketing SIG first.
This is necessary to avoid more than one contributor working on the same feature/change and to avoid someone from spending time on feature/change that would not be merged for any reason.
For smaller contributions use this workflow:
* Create an [issue](https://github.com/AlmaLinux/almalinux.org/issues) describing the changes.
* Await confirmation from contributors.
* Fork the project.
* Create a branch for your feature or bug fix.
* Add code changes, relevant documentation, etc.
* Send a pull request. All PRs should be made against the `master` branch. Once your pull PR is approved, a dev site will be automatically created based on the PR.
After one of the contributors has checked and approved the changes, they will be merged into master branch and will be automatically deployed to the live site.
#### For developers
To deploy local development environment, you will need following dependencies installed on your development host:
- hugo
Executing `hugo server` will deploy a nearly complete, ready to go development environment.
Executing `hugo server` will deploy a nearly complete, ready to go local development environment.
Localization will be incomplete unless you first run `find_missing_i18n_strings.py` and
`setup-pages-for-supported-languages.py`. Please do **not** commit the files which are output by these scripts.
Localization is important to us, and including localization formatting in your PR will be required. After you have formatted your text correctly, please run `find_missing_i18n_strings.py` and `setup-pages-for-supported-languages.py`, and then commit the changes to your branch. If you notice any issues with this script, please create an [issue](https://github.com/AlmaLinux/almalinux.org/issues) with details about the problem.
### Directories and modules
#### Directories and modules
- `/layouts/` - Hugo HTML templates
- `/layouts/partial` - commonly used template such as header and footer
@ -26,18 +64,21 @@ Localization will be incomplete unless you first run `find_missing_i18n_strings.
- `/static/` - static files
- `/content/` - Markdown content for pages
- `config.yaml` - Hugo config
- `find_missing_i18n_strings.py` - find strings used in layouts/templates which do not exist in the base language file
`i18n/en.json`
- `setup-pages-for-supported-languages.py` - create missing markdown pages for languages which do not exist.
By default Hugo will return 404 for markdown content without localized pages. This script copies the English
markdown to be served when translated copies are missing.
- `find_missing_i18n_strings.py` - find strings used in layouts/templates which do not exist in the base language file `i18n/en.json`
- `setup-pages-for-supported-languages.py` - create missing markdown pages for languages which do not exist. By default Hugo will return 404 for markdown content without localized pages. This script copies the English markdown to be served when translated copies are missing.
### Localization and translation
AlmaLinux OS localization and translation is managed using [Weblate](https://hosted.weblate.org/engage/almalinux/).
To contribute translations see [AlmaLinux OS](https://hosted.weblate.org/projects/almalinux/) localization project in Weblate.
almaLinux.org localization and translation is managed using [Weblate](https://hosted.weblate.org/engage/almalinux/). To contribute translations join the [AlmaLinux](https://hosted.weblate.org/projects/almalinux/) localization project in Weblate. Translations submitted through Weblate are automatically submitted to this repo as a pull request. Those pull requests are then reviewed by a member of the marketing SIG or another team lead, and merged as appropriate.
You can request new languages to be added by creating a ticket in [GitHub issues](https://github.com/AlmaLinux/almalinux.org/issues).
- All minor or cosmetic changes (typos, minor styling, etc) can be reviewed and approved by any contributor with merge rights
- All non-cosmetic changes to the website requires the approval of the Marketing lead
- Weblate automatically creates pull requests with new translated strings. Those pull requests are then reviewed by a member of the marketing SIG or another team lead, and merged as appropriate.
If you are interested in making a contribution there are a few ways you could help out the project.
## Contributing a blog post
# Contributing - Blog Posts
We welcome blog posts of almost any kind from our community! We accept content that covers topics that relate to AlmaLinux OS, the AlmaLinux OS Foundation. If you aren't sure if your blog post topic would be a good one, feel free to create an issue on this repo and ask! You can also join our chat and ask in the Marketing room.
@ -68,44 +64,6 @@ post:
- by submitting content to the AlmaLinux website, you acknowledge that you are aware of our [license policy](https://almalinux.org/p/the-almalinux-os-licensing-policy/), are affirming that you own all rights to publish said content.
- external links are allowed, but links to paywalled websites or obvious use of a blog post on the AlmaLinux site as an SEO builder for another website is prohibited. By default, external links should include a '[nofollow](https://en.wikipedia.org/wiki/Nofollow)' value. Exceptions can be requested in your pull request.
## Filing issues
You are free to use [GitHub issues](https://github.com/AlmaLinux/almalinux.org/issues) to submit bugs and for discussions related to the codebase.
### Reporting a Bug
Good bug reports can be very helpful. A bug is a demonstrable problem with the code or functionality.
Please use the [GitHub issues](https://github.com/AlmaLinux/almalinux.org/issues) and check if the issue has already been reported.
A good bug report should be as detailed as possible, so that others won't have to follow up for the essential details.
- Submit a bug in [GitHub issues](https://github.com/AlmaLinux/almalinux.org/issues)
### Requesting a Feature
1. [Search the issues](https://github.com/AlmaLinux/almalinux.org/issues) for any open requests for the same feature, and give a thumbs up or +1 on existing requests.
1. If no previous requests exist, create a new issue. Please be as clear as possible about why the feature is needed and the intended use case.
- Request a feature in [GitHub issues](https://github.com/AlmaLinux/almalinux.org/issues)
## Contributing code
If you plan to propose code changes it is required you create
an [issue](https://github.com/AlmaLinux/almalinux.org/issues) with a brief proposal and discuss it with us first.
This is necessary to avoid more than one contributor working on the same feature/change and to avoid someone from spending time on feature/change that would not be merged for any reason.
For smaller contributions use this workflow:
* Create an [issue](https://github.com/AlmaLinux/almalinux.org/issues) describing the changes.
* Await confirmation from contributors.
* Fork the project.
* Create a branch for your feature or bug fix.
* Add code changes, relevant documentation, etc.
* Send a pull request. All PRs should be made against the `master` branch. A dev site will be automatically created based on the PR. Localization will not be fully working as this pipeline does not run the localization scripts.
After one of the contributors has checked and approved the changes, they will be merged into master branch and will be included in the next deployment.
### Styling Guide
Please adhere to the styling guidelines listed below when contributing to the codebase.
@ -129,10 +87,3 @@ func main () {
````
Supported highlighting languages can be found [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages).
## Approval of changes
Before any changes can be merged:
- All minor or cosmetic changes (typos, minor styling, etc) can be approved and merged by any contributor with master merge rights
- All non-cosmetic changes to the website requires the approval of the Marketing lead
Hosted Weblate
1 year ago