forem / admin-docs

Empowering Forem Creators

Forem 🌱

For Empowering Community

Welcome to the Forem codebase, the platform that powers dev.to. We are so excited to have you. With your help, we can build out Forem’s usability, scalability, and stability to better serve our communities.

What is Forem?

Forem is open source software for building communities. Communities for your peers, customers, fanbases, families, friends, and any other time and space where people need to come together to be part of a collective. See our announcement post for a high-level overview of what Forem is.

dev.to (or just DEV) is hosted by Forem. It is a community of software developers who write articles, take part in discussions, and build their professional profiles. We value supportive and constructive dialogue in the pursuit of great code and career growth for all members. The ecosystem spans from beginner to advanced developers, and all are welcome to find their place within our community. ❤️

Table of Contents

• What is Forem?
• Table of Contents
• Community
• Contributing
• Getting Started
  • Installation Documentation
• Developer Documentation
• Vulnerability disclosure
• Acknowledgements
• License

Community

For a place to have open discussions on features, voice your ideas, or get help with general questions please visit the discussions section.

Contributing

We encourage you to contribute to Forem! Please check out the Contributing to Forem guide for guidelines about how to proceed.

Getting Started

This section provides a high-level quick start guide. If you're looking for a more thorough installation guide (for example with macOS, you'll want to refer to our complete Developer Documentation.

We run on a Rails backend, and we are currently transitioning to a Preact-first frontend.

A more complete overview of our stack is available in our docs.

To launch Forem in Gitpod, navigate to https://gitpod.io/#https://github.com/{your_github_username}/forem.

Installation Documentation

Please see our installation guides:

• MacOS, without containers
• Linux, without containers

Developer Documentation

Check out our dedicated docs page for more technical documentation.

Vulnerability disclosure

Forem is the open source software which powers DEV.

We welcome security research on DEV under the terms of our vulnerability disclosure policy.

Acknowledgements

Thank you to the Twemoji project for the usage of their emojis.

Thank you to Uffizzi for providing ephemeral environments to preview pull requests.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Please see the LICENSE file in our repository for the full text.

Like many open source projects, we require that contributors provide us with a Contributor License Agreement (CLA). By submitting code to the Forem project, you are granting us a right to use that code under the terms of the CLA.

Our version of the CLA was adapted from the Microsoft Contributor License Agreement, which they generously made available to the public domain under Creative Commons CC0 1.0 Universal.

Any questions, please refer to our license FAQ doc or email [email protected].

Happy Coding ❤️

⬆ Back to Top

admin-docs's Issues

Admin Member Detailed View

Explain the changes

https://forem.team/ridhwana/admin-member-detailed-view-12a8

Suggested changes

You can find a writeup on the changes in the forem.team article above, and some screenshots as well. In addition, this is deployed on Canary too: https://canary1.forem.wtf/admin/users/14.

However, please ping us in #pod-admin-experience for any more information.

Additional context

Update Documentation Around Admin Onboarding Flow

Explain the changes

Once the updated Admin Onboarding flow is live, the documentation pertaining to the Admin Onboarding flow, the "First User Registration" section to be precise, will need an update.

Suggested changes

The following changes will need to be made:

• Updates to the documentation's copy
• Updates to the documentation's pictures

Additional context

Once the revamped Admin Onboarding flow is live (date TBD), I will coordinate with the team on updating the documentation. I am more than happy to help where I can!

Document Profile Field customization

Explain the changes

Profile Fields have been added and enabled to the admin area, but there's no documentation for this page yet.

Suggested changes

Describe the relationship between field groups and fields, the types of fields available, and the different "target areas" (sidebar, main profile header, etc), so creators can confidently make decisions about these fields.

Additional context

Finalizes work in https://github.com/forem/forem-internal-eng/issues/352

Update Forem developers API docs guide

API Docs at https://developers.forem.com/contributing-guide/api need to be updated with new name/location/process for generating the API documentation site

Update Documentation Related to the Admin Member Detail View

Explain the changes

Once the updated Admin Member Detail View is live, any documentation referencing the Admin Member View, the "User Roles" section screenshots, the "Suspending Users" section, and the "Removing Spam" section to be precise, will need to be updated accordingly.

Suggested changes

The following changes will need to be made:

• Updates to the documentation's copy, including references to links
• Updates to the documentation's pictures

Additional context

The revamped Admin Member View will hopefully go live in the upcoming weeks, but the exact date is still TBD -- more updates to come! Additionally, I am more than happy to help where I can, so please let me know where and how I can be of assistance. 😊

Expand auto-vomit functionality

Explain the changes

forem/forem#14858

This PR will mean that Spam Trigger Keywords creates an auto vomit on the user if their name contains one of the spam keywords, i.e. "call girls".

Contact email address

I'm logging this issue but just waiting for @JennieOcken's confirmation that the feature behaves as product expects it to. I'll add a comment here when its ready to be worked on and co-ordinate the deploy.

Explain the changes

Introduction of a contact email link.

Currently across the site, we use the default_email as the email. This email displays the email address from which emails are being sent from for Forem Cloud instances that are configured with Sendgrid. This is usually [email protected].

However, this default_email is also being used for contact links across the site. As an example it will say:
"Contact [email protected] for custom bulk pricing and partnerships."

Hence, I've added a specific contact field. The contact field gives the Forem an opportunity to provide an email that are used for any contact links. It is the email where users can get in touch with the Forem or their team."

In doing so, I took the opportunity to clean up the user interface and experience a little bit.

• I've removed the "email Digest Frequency Section" and moved the "periodic email digest" field to the "Emails Section"
• I've added the contact field to the email section as well
• Finally, I've removed the "Default" field form the Emails section. Instead we've added a note in this PR that states "As a Forem Cloud client, we provide an email server managed by the Forem team. All settings are managed by us and the from and reply email addresses are set as [email protected]. However, you can override this to use your own email server." which serves a similar but more informative purpose.

BEFORE:

AFTER:

I want to make a note that the default value for the contact field will however be the "default email" that is used for Sendgrid emails. This is so that views render properly with a value on first load.

Suggested changes

From what I can see, it would be updates to:

1. https://admin.forem.com/docs/advanced-customization/config/emails (add contact email address and remove default)
2. https://admin.forem.com/docs/advanced-customization/config/email-digest-frequency (move the periodic digest frequency to (1) above.

Additional context

A demo:
https://www.loom.com/share/e1615e5442d5422382edb5db603ead43

Please feel free to ping me for any screenshots etc.

cc @ellativity

Adding documentation around blocking a domain

Explain the changes

Addressing the following issue: Allow admins to set a list of disallowed emails for sign up. · Issue #281 · forem/rfcs

The following pull requests introduced changes to complete the issue:

• Guarding against spam from OAuth Sources by jeremyf · Pull Request #15404 · forem/forem
• Adding ability to block domains from registration by jeremyf · Pull Request #15397 · forem/forem
• Moving blocked registration domains up by jeremyf · Pull Request #15403 · forem/forem

Suggested changes

This change impacts the administrative settings, by introducing a new field. When you fill out a comma separate list of domains, and save the change, future attempts to register via that OAuth provider will fail if their associated email is from any of the blocked domains.

Additional context

Note: There is an edge case around whether or not they've stated "Only allow emails from this domain." If that is set, the OAuth2 authentication and email checks will also honor that.

Explain new simpler process for submitting sitemap to Google Search Console

Explain the changes

Admins can now be instructed to submit /sitemap-posts.xml as the default way to submit to Google Search Console if this is merged:

forem/forem#14857

They can optionally be instructed to submit monthly sitemaps if they want to get specific breakdowns month-over-moth, but this is more advanced functionality for very large Forems. This functionality has already been in place, but we did not have the more basic functionality in place.

Update Authentication page with Google SSO instructions

The Authentication page is now missing Google SSO instructions for admins to be able to configure Google SSO on their Forems.

Here is the announcement post on forem.dev

Add "featured" option for podcasts.

Explain the changes

If this PR goes through, forem/forem#15004, admins now have the option to select one or two podcasts as "featured". This means they show up in the /pod in a special place.

[bug] overflow in x direction

Explain the type of resource

when I was surfing the website ie (admin forem)[https://admin.forem.com/] there was responsiveness bug in the website

Additional context

video6284860287443012375.mp4

Update `/advanced-customization/listings`

Explain the changes

As @amywtlin describes in this issue, Listings are being placed behind a feature flag. We need to update the docs to reflect this change and instruct admins on how to enable Listings if they want to.

Suggested changes

@jeremyf has written these instructions complete with screenshots: How to enable the listing_feature

Additional context

This needs to happen by Friday 24 February 2022.

Unpublish all posts

Explain the changes

If this is merged, we will need to add it to the docs:

forem/forem#15054

Our success team should basically understand how to explain this.

Update "Forem Setup Checklist" Documentation

Explain the changes

With the new-and-improved Creator Onboarding flow, the "Verify Setup" banner and "Getting Started" section are no longer as useful as they once were. This being said, we have removed the "Verify Setup" banner from the site and plan on removing the "Getting Started" section from the Config. In our Admin documentation, we have a brief section that explains both the "Verify Setup" banner and the "Getting Started" section in the Config. With the removal of both, we'll also want to remove the documentation for them.

Suggested changes

The following changes will need to be made:

• We will need to remove the references to the "Verify Setup" banner and "Getting Started" section from the "Forem Setup Checklist" documentation, which can be found here.

Additional context

The PR for the removal of the "Verify Setup" banner has been merged, but the PR for the removal of the "Getting Started" section is in a draft mode and will remain in a draft mode until I speak with @Ridhwana further about how to best communicate this change. This being said, I will provide updates on when the work is actually merged so that we can coordinate the removal of the references to this section from the documentation (if that works for y'all!). 😊

Add API doc generation to Forem Developers guide

We should add a section to https://developers.forem.com explaining how to API documentation works via RSwag, and how to generate docs.

Clarify connect chat feature is deprecated

Explain the changes

The documentation at https://admin.forem.com/docs/advanced-customization/chat-channels describes the "connect" chat functionality. Since this is feature-flagged and deprecated, the page should clarify that this may not be available for all Forems (or removed entirely to avoid confusion?) The feature flag was intended to permit sites already using this to migrate to another solution (and is intended to be temporary).

Suggested changes

Either remove chat-channels.md or add clarifying language under the Overview heading that highlights this is a limited feature for some existing Forems, and likely not visible in most sites, or new Forems. A link to Ben's forem.dev post indicating the rationale might be useful.

Additional context

Update Liquid Tag/Markdown Documentation

Explain the changes

This one isn't so straightforward. We need to:

1. Update our Liquid Tag docs to be in line with the new Unified Liquid Embed project as discussed in this post.
2. Remove existing duplicated documentation (e.g., don't repeat knowledge)
3. Determine the best places to put this documentation

Suggested changes

Not a straightforward update to our admin docs. This is instead about updating user facing docs.

Additional context

Whatever user-facing docs we create here should be updated across all Forems.

Make it clearer in "Editing a Tag" how to create and edit a template

Explain the changes

Update the Editing a Tag page to more clearly draw out that this is where you can find out how to create and edit a post template.

Suggested changes

Update the first paragraph of the Submission Template section to read:

Submission Template: This is where you create a post template! Place text here that will appear when you create any new posts under this tag. You can share these templates by directing people to /new/{tag_name}. This is especially useful when encouraging members to post about a topic in a structured format. This field takes markdown.

Additional context

The reason I place that sentence right at the start is so that it shows up when you search the admin docs for "template" -- currently, it shows: "Submission Template: Placeholder text that appears when creating" -- which doesn't instantly clue in someone who's looking for information on creating templates that this is where to go. Assuming that the same general number of characters shows up in the search preview, it should now show: "Submission Template: This is where you create a post template!" -- which will be more eye-catching in the search preview.