Add CONTRIBUTING.md with blog post creation instructions #44
Conversation
…DME to add a reference to it
✅ Deploy Preview for spyder-website-preview ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
@CAM-Gerlach, please take a look at this one. |
|
@CAM-Gerlach please remember to take a look at this, I have recently updated it to make it more comprehensive. |
CAM-Gerlach
left a comment
CAM-Gerlach
left a comment
There was a problem hiding this comment.
My major high-level comment below is that we really should reuse our battle-tested standard contribution guide template here shared with many of our other repos (including the old website) as much as practical instead of re-inventing (and maintaining) the wheel, adding any substantial rope-specific bits from here and making any generic improvements to the shared template for re-use elsewhere.
I've provided specific suggestions on the repo-specific Contributing Guide sections I suggest retaining (as well as the entirety of the Readme, given our template for that only has a handful of widely-standardized elements), and more general comments on the remaining sections I suggest replacing with those from our standard template mentioning major issues or valuable bits to retain.
Given the scope of the change and particularly the delay here, I'd be more than happy to take care of the integration with a commit here if you prefer—just let me know!
There was a problem hiding this comment.
Well, I wrote a long and detailed file level comment here proposing a detailed step by step strategy for integrating this with our standard contributing guide template used on other repos, but after spending an hour writing it, fucking GitHub somehow got amnesia and wiped it when I accidentally hit back (unlike literally any other GitHub review comment normally), just when I was thinking of copying it to have a backup just in case GitHub fucked up. RIP...
Instead of reinventing the wheel here developing and maintaining an entirely separate contribution guide, IMO we should instead start with our standard template used on most of our other repos, adding/replacing the repo-specific bits from here as needed, and contributing any common changes you find valuable upstream to the aforementioned master template so they can be re-used elsewhere too.
Given the scope of the change and particularly the delay here, I'd be more than happy to take care of the integration with a commit here if you prefer—just let me know!
Here are the specific integration steps I suggest:
- Delete "Setting Up a Development Environment with Nox (Recommended)", "Installing and Using the Pre-Commit Hooks", and "Decide which branch to use" sections
- Replace "Setting Up a Development Environment Manually" and "Building the Project" with the content of "Development setup", which to be consistent with the others can be called "Installing and building" or similar
- Add the content of the "Add the upstream remote" section to the end of the "Cloning the repository" section, as without Nox to do it for you, it is better mentioned at that point
- Find/replace "Spyder-Infra" (in lowercase and Title Case variants) and the remaining couple
_FIXME_placeholders that are relevant - "Creating Blog Posts" can go after "Contributing Changes", since it provides detailed advice for a specific sub-type of code contribution after offering an overview of the overall contribution flow
- We can add a section "Make and test your changes" between the "Prepare" and "Commit" sections of "Contributing Changes" (in the upstream template too), reminding users to run
npm run devand ensure they appear as expected (step 1 of your "PUll request process". - Standards and Conventions
- "Key standards" should be updated to list the specific, well, standards and conventions this repo follows (rather than generic ChatGPT-sounding advice, jaja)
- If desired to be retained, the "File structure" summary can go as a second section under here
- The detailed specifics in the "Reporting Issues" section of your version can be added to the "Reporting Issues" section of the template (and some of it at least is worth adding upstream)
- The Questions section can be kept, added to the end and also contributed upstream
- The remaining sections few sections are redundant with those added in the template and elsewhere
| ## Table of Contents | ||
|
|
||
| - [Contributing to the Spyder Website](#contributing-to-the-spyder-website) | ||
| - [Table of Contents](#table-of-contents) | ||
| - [Getting Started](#getting-started) | ||
| - [Development Setup](#development-setup) | ||
| - [Types of Contributions](#types-of-contributions) | ||
| - [Creating Blog Posts](#creating-blog-posts) | ||
| - [Adding New Authors](#adding-new-authors) | ||
| - [Creating the Blog Post](#creating-the-blog-post) | ||
| - [Code Contributions](#code-contributions) | ||
| - [Guidelines](#guidelines) | ||
| - [File Structure](#file-structure) | ||
| - [Reporting Issues](#reporting-issues) | ||
| - [Pull Request Process](#pull-request-process) | ||
| - [Review Process](#review-process) | ||
| - [Style Guidelines](#style-guidelines) | ||
| - [Questions?](#questions) |
There was a problem hiding this comment.
Is this auto-updated, or does it have to be done manually? We use doctoc for this on our other repos (which we'll get for free if and when we add our pre-commit config here).
There was a problem hiding this comment.
I will remove it for now and we can auto-generate it later using pre-commit.
| ## Getting Started | ||
|
|
||
| 1. **Fork the repository** from [spyder-website](https://github.com/spyder-ide/spyder-website) | ||
| 2. **Clone your fork** locally: | ||
| ```bash | ||
| git clone https://github.com/YOUR-USERNAME/spyder-website.git | ||
| cd spyder-website | ||
| ``` | ||
| 3. **Create a new branch** for your changes: | ||
| ```bash | ||
| git checkout -b your-feature-branch | ||
| ``` |
There was a problem hiding this comment.
Redundant with the Cloning the repository section of our standard template, aside from the "create a new branch" step which interleaves and mixes up one-time step actions (forking, cloning, installing dependencies) with every-time contribution flow (branch creation, building, committing, etc)—our standard template keeps them cleanly separated.
| ## Community | ||
|
|
||
| - 🐍 **Main Project**: [Spyder IDE](https://github.com/spyder-ide/spyder) | ||
| - 💬 **Discussions**: [GitHub Discussions](https://github.com/spyder-ide/spyder/discussions) |
There was a problem hiding this comment.
Uh, no, we don't use this and it 404s.
Co-authored-by: C.A.M. Gerlach <[email protected]>
3 participants
This PR adds a
CONTRIBUTING.mdfile with instructions to create blog posts. This solves Issue #9.