Before you begin:
- The pmem.io website is powered by the Hugo static site generator and hosted on GitHub Pages.
- Have you read the code of conduct?
- Review the existing issues and see if we accept contributions for your type of issue.
You can contribute to the pmem.io content and website in several ways. This GitHub repository is a place to discuss and collaborate on pmem.io! A small, but mighty team is maintaining this repo. To preserve our bandwidth, off topic conversations will be closed.
Discussions are where we have conversations. If you have a great new idea or suggestion for the site, or want to share something amazing you've learned in our docs, start a new discussion on the PMem Forum.
Issues are used to track tasks that contributors can help with. Search the open issues to see if there's something you want to help with.
If you've found an issue in the content or the website functionality that should be updated or fixed, search open issues to see if someone else has reported the same thing. If it's something new, open a new issue. We'll use the issue to have a conversation about the problem you want to fix. We highly recommend using the following title format:
[Page|Section] <Object> and <Defect>
A good title is:
[Developer Hub] 'Developer Tools' Cards whitespace should be reduced
Where "Developer Tools Cards" is the Object/Thing, and "whitespace should be reduced" is the defect, or thing to fix.
A bad title is:
I don't like the spacing between the Dev Hub tools
A pull request is a way to suggest changes in our repository.
When we merge those changes, they should be deployed to the live site within 24 hours. To learn more about opening a pull request in this repo, see Opening a pull request below. The site will automatically get rebuilt using GitHub Actions, but it can take time to update the cached versions across the globe.
We are a small team working hard to keep up with the demands of an active community. Unfortunately, we just can't help with support questions in this repository. If you are experiencing a problem with persistent memory, please reach out to the Community. Any issues, discussions, or pull requests opened here requesting support will be reviewed and addressed.
The source content in this repository is written in English. We are working hard to internationalize the site to make it available in multiple languages. We are currently not accepting translation contributions, but may do so in the future.
If you spot an issue with the site, would like to contribute new content, or would like to fix or refresh the styling of the website, please open a new issue. We'll use the issue to have a conversation about the contribution.
You can browse existing issues to find something that needs help!
You must make changes in a fork of this repository. Pull requests directly to this repository will not be accepted.
Note: It's important for your fork to be named a bit differently than our upstream version.
It's best to name your fork <your_username>.github.io instead of proposed pmem.github.io. Thanks to this change, it's possible
for you to generate a website like https://<your_username>.github.io. See section Preview on your fork
below for more details.
You can fork this project using several methods:
- Fork your own copy of pmem/pmem.github.io to your GitHub account by clicking the Fork button in the top right.
- Getting started with GitHub Desktop will guide you through setting up Desktop.
- Once Desktop is set up, you can use it to fork the repo!
- Fork the repo so that you can make your changes without affecting the original project until you're ready to merge them.
Fork with GitHub Codespaces
- Fork, edit, and preview using GitHub Codespaces without having to install and run the project locally.
Before making any changes, create a local branch.
Make your changes to the file(s) you'd like to update.
Learn the structure of this repository, what file(s) should be modified, and where to create new content below.
Here's some information that might be helpful while working on the pmem.io website repository. The following describes the directory structure of this repository.
- Archetypes - Archetypes are content template files in the archetypes directory of the project that contain preconfigured front matter. These will be used when you run
hugo new. If you need to modify an archetype file, please consider that content created using these templates will also have to be modified and the layout files may need to be updated to support the change(s). If you create a new archetype file, you will need to also create a layout file to render the post types. - Content - This is where the majority of the content for the website resides. Directories within the
/contentdirectory are called Sections and represent the site layout. For example: blog, community, documents,. events, faq, learn, news, solutions, videos, etc. Hugo uses the Goldmark Markdown processor which is fully CommonMark-compliant. - Data - Most of the pages use YAML files from this folder to render the content. If you want to make changes to a page, you'll likely only need to modify the corresponding yml file here and not the layout file.
- Static - Files in the
/staticfolder are included in the website without modification. Static files include css, images, pdf, etc. Read more about static files in the Hugo documentation. - Themes - The website uses a custom theme based on Canvas | The Multi-Purpose HTML5 Template.
Hugo uses the Goldmark Markdown processor which is fully CommonMark-compliant.
If you are creating new content, you should use the hugo new command to generate the markdown file. For example, to create a new Blog article with the title "My Amazing Blog Article", run:
$ hugo new blog/<current_year>/my-amazing-blog-article.md
Other examples:
// Create a new Event
$ hugo new events/my-super-event.md
// Create a new News article or Announcement
$ hugo new announcements/<current_year>/my-big-news-article.md
// Add a new solution
$ hugo new solutions/vendor-product.md
// Add a new video
$ hugo new videos/video-title.md
Note: If you forget the .md file extension, Hugo will give you a generic front matter, which isn't what you want.
You can now edit the newly created file. Update the front matter, then add your content. Some content types, such as videos and solutions, require you to update the front matter only with no content. Blog and News articles require both front matter and content.
Many content types require images - blogs, news, solutions, etc. You should use images that you have ownership of or permission to use. If you use an image from the Internet, please attribute the original owner. There are many that offer open license use of their images and illustrations for any project, commercial or personal without attribution or costs. Here's a list of some of them:
Photos
Illustrations & Vector
If you wish to make changes to pages, styling, or the theme, you'll need to create and modify files in the /data and /themes/pmem-hugo directories. The data and content is intentionally decoupled from the theme to allow future styling changes without having to rewrite the content.
You must review your changes using a local version of Hugo to confirm the site builds without errors and the changes you made render as you expect and do not break the website. You can run Hugo locally or on a remote host on macOS, Windows, Linux, OpenBSD, and FreeBSD. See the Install Hugo documentation for step-by-step instructions.
- You'll need Hugo 0.88.0 or newer to run the site locally.
- Are you contributing to markdown? Hugo uses the Goldmark Markdown processor which is fully CommonMark-compliant.
When you're done with changes and commit(s) are ready, you should enable page build on your fork. It's required to do this
only once for a new fork, and it's especially important if you were using pmem.io repository before we switched to using Hugo.
Before enabling page build, please make sure your repository is called <your_username>.github.io. If you need to, you can update
the name in the repository settings, at any moment (both - the old one, and the new one - will be working correctly).
To enable the GitHub Actions workflow (defined within the repository in .github directory) you have to turn on all defined workflows
in Actions tab in the repository page and in the Settings page (Actions section). Then, in the Settings, in the Pages
section you have to set up Source to gh-pages branch (folder should be set to /(root)) and just hit Save.
Now, whenever you push any changes onto main branch, the "pages build and deployment" workflow will run and deploy your refreshed
website to https://<your_username>.github.io. You can browse it to review your changes.
Please note that some links may still re-direct you to the original https://pmem.io website (we're working on this issue).
When you're done making changes and you'd like to propose them for review, use the pull request template to open your PR (pull request). It's best to include (e.g., in the PR's description) the link to your generated website (see section above).
Alternatively, you can use the GitHub user interface ✏️ for small changes, like fixing a typo or updating a readme.
Once you submit your pull request (PR), others from the community will review it with you.
- The first thing you're going to want to do is a self review.
- After that, we may have questions, check back on your PR to keep up with the conversation.
- Did you have an issue, like a merge conflict? Check out our git tutorial on how to resolve merge conflicts and other issues.
While commenting pull requests we always conduct appropriately:
- Reviews are always respectful, acknowledging that everyone did the best possible job with the knowledge they had at the time.
- Reviews discuss content, not the person who created it.
- Reviews are constructive and start conversation around feedback.
You should always review your own PR first.
For content changes, make sure that you:
- Confirm that the changes meet the user experience and goals.
- Test your changes using a Desktop, Tablet, and Mobile device using different browsers to verify the site renders correctly. There are many online services to assist you with these tests.
- Compare your pull request's source changes to staging to confirm that the output matches the source and that everything is rendering as expected. This helps spot issues like typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Remember that lists and tables can be tricky.
- Review the content for technical accuracy.
- Copy-edit the changes for grammar and spelling.
- Check new or updated Go statements.
- If there are any failing checks in your PR, troubleshoot and resolve them until they're all pass.
- Pull request template
When you open a pull request, you must fill out the "Ready for review" template before we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request.
We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
As you update your PR and apply changes, mark each conversation as resolved.
Congratulations! The whole PMem community thanks you.