Added tweaks suggested by Fred to prepare for Natron website transiti…

…on (#14) * Tweak installation guide with more accurate information * Added requested information for Apple Silicon * Added requested information for Apple Silicon - Downloads section now shows that the main macOS downloads are for Intel only - Information added about how to run Natron on Apple Silicon macs below main downloads - Link to the Natron 2.6.0 pre-release (that has Apple Silicon support) added to `_config.yml` - Also changed the `branch` field in `_config.yml` (even though we don't use it for anything right now) to match Natron 2.5's branch to avoid future confusion * A few minor wording edits for better flow * Updated README with detailed information for creating a new release * Changes * to - in lists * Spelling fix and link fix * Change link text Improves accessibility, "here" is not descriptive link text * Update about.md copy with Hank's suggestions Co-authored-by: Henry Wilkinson <[email protected]> * Punctuation fix * Adds link to GitHub past releases --------- Co-authored-by: Henry Wilkinson <[email protected]>
Shrinks99 · Dec 23, 2024 · 047a75e · 047a75e
1 parent 2f53d72
commit 047a75e
Show file tree

Hide file tree

Showing 7 changed files with 87 additions and 31 deletions.
diff --git a/DEVELOP.md b/DEVELOP.md
@@ -2,12 +2,16 @@
 
 Natron's website uses Jekyll, a static site generator. It usually saves us a lot of time reduces our trouble, but we know it can be confusing to many newer developers and get *them* in lots of trouble. So, here is a reliable means of developing Natron's website for Mac users, Windows users, and GNU/Linux users!
 
+If you're an absolute beginner, we recommend taking a look at the [terminal cheat sheet](https://terminalcheatsheet.com/) as well as the [Atlassian tutorials on version control and git](https://www.atlassian.com/git/tutorials/what-is-version-control) before continuing. In addition, it may be helpful to look through the [Jekyll setup guide](https://jekyllrb.com/docs/step-by-step/01-setup/).
+
 If you run into any issues, look at the FAQ and [Development Gotchas](#development-gotchas) section at the bottom of this guide.
 
 ## Installing prerequisites for development
 
 ### Prerequisites for all operating systems
 
+Before doing anything, check that you have a reliable internet connection. Additionally, Windows users should run all the listed commands in **powershell**, not the command prompt.
+
 Make sure you have `git` installed. If you are using macOS or GNU/Linux, you likely already have it installed; Windows users can download and run the installer from [its official download page](https://git-scm.com/download/). Check that you have `git` correctly installed by running this on Mac/Linux:
 
 ```bash
@@ -22,7 +26,7 @@ where git; if %errorlevel% neq 0 echo git is not installed.
 
 Now, head to correct instructions for your operating system:
 
-- [GNU/Linux](#gnu/linux-instructions)
+- [GNU/Linux](#gnulinux-instructions)
 - [Windows](#windows-instructions)
 - [macOS](#macos-instructions)
 
@@ -68,7 +72,7 @@ If you would like to troubleshoot Jekyll, run `bundle exec jekyll doctor` which
 Finally, you can run bundler which automatically installs Jekyll as well as starts a development server:
 
 ```bash
-DISABLE_WHITELIST=true # allows plugings to run
+DISABLE_WHITELIST=true # allows plugins to run
 bundle install && bundle exec jekyll serve
 ```
 
@@ -111,7 +115,16 @@ $env:RBENV_ROOT = "$HOME\Ruby-on-Windows"
 & "$env:RBENV_ROOT\rbenv\bin\rbenv.ps1" init
 ```
 
-Now open another powershell terminal, and rbenv should automatically start downloading the Ruby toolchain. If it does not, run:
+`rbenv` also requires that the free 7-zip file archiver is installed. If not, then [head to the 7-zip website](https://www.7-zip.org/). Then run `notepad $profile` and add the following line:
+
+```powershell
+# Add 7zip to PATH
+$env:Path += ';C:\Program Files\7-Zip'
+```
+
+Test by running `7z`, if it simply shows a bunch of options (it is quite verbose!) but no "executable not found"-style error, you may proceed with the rest of these steps.
+
+Now (assuming you either have installed 7-zip or have followed the steps to install it) open another powershell terminal, and rbenv should automatically start downloading the Ruby toolchain. If it does not, run:
 
 ```powershell
 rbenv install 3.3.3
@@ -155,7 +168,7 @@ Follow the same steps as in the GNU/Linux guide, with the one difference being t
 
 Our development workflow uses Git, which tracks development changes so that we can easily synchronize work by multiple developers, locate any change in history, and not worry about losing work. Git relies on the concept of _branches_ and _commits_. A commit is any change: it can be anything from editing an existing file, creating a new file, to deleting a file. Commits happen on _branches_, which are like paths for commits. A quick reference to Git's many, many commands, as well as links to resources for beginners, can be found [here](https://learnxinyminutes.com/docs/git/). We host our Git repository and collaborate on [GitHub](https://github.com/), and a starting guide for GitHub can be found [here](https://docs.github.com/en/get-started/start-your-journey).
 
-It is *strongly encouraged* to create a new branch for any new additions, via `git checkout -b my-new-branch-name`, as this will avoid [many issues](https://stackoverflow.com/questions/64369860/github-no-file-changes-but-many-commits-when-comparing-branches). Open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) once you are finished making your changes and have pushed them to GitHub.
+It is _strongly encouraged_ to create a new branch for any new additions, via `git checkout -b my-new-branch-name`, as this will avoid [many issues](https://stackoverflow.com/questions/64369860/github-no-file-changes-but-many-commits-when-comparing-branches). Open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) once you are finished making your changes and have pushed them to GitHub.
 
 ### Important contributing information
 
@@ -171,10 +184,12 @@ Due to the nature of our development setup, there are lots of hidden surprises t
     - This is because the correct syntax is `{% include component.html param="value" %}`, with the include html path **not surrounded by quotes** (i.e. not `"component.html"`)
 - My site variables are not being updated!
     - Reload the development server, open a new terminal if necessary, as Jekyll's development server does not seem to reload config files
+- I am getting some variation of the error `"<command> not found"` or `"<command> is not recognized as a file, script, or operable command"`
+	- Try opening a new terminal window and navigating to the natron website folder again. This reloads the shell and allows it to find any newly-installed developer tools and components
 
 ## FAQ
 
 - Why did you use Jekyll? Why not Hugo/Next.js/Gatsby?
     - This is because Jekyll is native to GitHub, and we originally wanted to use GitHub pages' native Jekyll support, though we ended up switching to GitHub actions to reduce dependencies and use a more recent version of Jekyll
 - Why is the Git repo so big?
-    - We include images, brand assets and third-party binary files necessary for Natron that are not available anymore, the Jekyll site itself is relatively small
+    - We include images, brand assets and third-party binary files necessary for Natron that are not available anymore, the Jekyll site itself is relatively small
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -65,6 +65,7 @@ GEM
 PLATFORMS
   x64-mingw-ucrt
   x86_64-darwin-20
+  x86_64-darwin-23
   x86_64-linux
 
 DEPENDENCIES

diff --git a/README.md b/README.md
@@ -4,23 +4,25 @@
 
 ## Development
 
-We're open to any contributions! To contribute, make sure you have a decent grasp of these things:
+We're open to any contributions! To contribute, make sure you have a decent grasp of these things (or have a willingness to learn them!):
 
-* The command line
-* Web design
-* HTML/CSS and SCSS
-* Some prior experience with Jekyll
+- The command line
+- Web design
+- HTML/CSS and [SCSS](https://sass-lang.com/)
+- Some prior experience with [Jekyll](https://jekyllrb.com/)
 
 Note that if you're a beginner programmer and this is your first time working on an open-source project, we advise you to read [the detailed development guide](DEVELOP.md). The guide is also helpful if you encounter issues in the setup process. The process described below assumes a pre-existing knowledge of version control systems and Jekyll in general. If that's ok with you, follow these steps to quickly get started:
 
 ### Getting Dependencies
 
 Make sure you have `git` already installed. This website also requires Jekyll, a static site generator we use to generate markup from templates. Installing Jekyll is generally a variation of these steps:
 
-* Step 1: Install `rbenv` via `brew install rbenv` on macOS with [Homebrew](https://brew.sh/) installed, `sudo apt install rbenv` on Debian Linux distros, `yay -S rbenv` on Arch-based distros, or compiling manually from its sources at <https://github.com/rbenv/rbenv>. For Windows, follow the instructions for [rbenv for Windows](https://github.com/ccmywish/rbenv-for-windows), just making sure to substitute `$env:RBENV_ROOT = "$HOME\Ruby-on-Windows"` wherever it is mentioned.
-* Step 2: Run `rbenv init` and open a new terminal (not necessary on Windows)
-* Step 3: Run the command `rbenv install 3.3.3 && rbenv global 3.3.3` (or any recent version) (not necessary on Windows, it auto-installs)
-* Step 4: Now, open a new terminal again, and run `gem install bundler` - this gives you access to the `bundle` command which (confusingly) is what installs Jekyll!
+- Step 1: Install `rbenv` via `brew install rbenv` on macOS with [Homebrew](https://brew.sh/) installed, `sudo apt install rbenv` on Debian Linux distros, `yay -S rbenv` on Arch-based distros, or compiling manually from its sources at <https://github.com/rbenv/rbenv>. For Windows, follow the instructions for [rbenv for Windows](https://github.com/ccmywish/rbenv-for-windows), just **making sure** to substitute `$env:RBENV_ROOT = "$HOME\Ruby-on-Windows"` wherever it is mentioned.
+- Step 2: Run `rbenv init` and open a new terminal (you may not _have_ to do this depending on your system and terminal setup, but it's recommended)
+- Step 3: Run the command `rbenv install 3.3.3` and then `rbenv global 3.3.3` (other versions of Ruby _may_ work but are untested and may break things). This is *usually* not necessary on Windows (it auto-installs) but if the next step(s) don't work, run the aforementioned command and try again
+	- Be aware that this may take a while (~5 min. depending on your internet connection)
+	- On windows, this assumes you have 7-Zip installed and on your PATH. Read the [detailed developer guide](DEVELOP.md) otherwise.
+- Step 4: Now, open a **new** terminal again, and run `gem install bundler` - this gives you access to the `bundle` command which (confusingly) is what installs Jekyll!
 
 ## Building With Jekyll
 
@@ -32,9 +34,9 @@ git clone https://github.com/Shrinks99/NatronGitHub.github.io && cd NatronGitHub
 
 Build with Jekyll in three steps:
 
-* `bundle install` to install all the dependencies
-* `bundle exec jekyll build` to build the site
-* `bundle exec jekyll serve --incremental` to start Jekyll at <http://localhost:4000>
+- `bundle install` to install all the dependencies - this may take quite a while! Windows users may need to run this in a Powershell session with **administrator permissions**
+- `bundle exec jekyll build` to build the site
+- `bundle exec jekyll serve --incremental` to start Jekyll at <http://localhost:4000>. You may also add the `--livereload` flag so that the development server reloads automatically on edits to the source code (which can be a big time-saver!)
 
 Navigate to <http://localhost:4000> in the browser and get going!
 
@@ -66,14 +68,32 @@ All color variables are referenced as both P3 and an sRGB fallback.  Variables c
 
 SVGs can only have their colors set with variables if they exist in the DOM.  This matters most for SVGs set to our brand colors & 100% white.  If the SVG is not using these colors _it doesn't have to be embedded!_  Otherwise, it should be.
 
-### Authoring an Update Post
-
-After building and setting up the release through GitHub Releases...
-
-1. Create a standard release graphic: Natron project file and instructions on how to do this are available in the releasegraphic folder in `/templates`.  Place the generated image in `/img/news/releases`.
-2. Author an update post: Markdown template also available in `/templates`, be sure to change the relevant info in both the file name and the front matter section, most of the body text can be copied from the GitHub `CHANGELOG.md`, please include any extra information about the release before the "Major Changes" section.
-3. Change the download links by setting the variables in `_config.yml`.
-4. Publish to main!  Bonus points for testing the site locally first ;)
+### Authoring an Update Post (for new releases)
+
+> **Note:** This assumes stable releases, _not_ pre-releases
+
+After building and setting up the release through GitHub Releases, the website can be updated as follows:
+
+1. Create a standard release graphic:
+    - A Natron project file that automatically generates a release graphic is available in the releasegraphic folder in `/templates`. The instructions for using it are [here](templates/releasegraphic/README.md).
+    - After generating the release graphic, place it in `/img/news/releases`.
+2. Author an update post:
+	- Copy the markdown post template in `/templates` (the one titled `yyyy-mm-dd-release-x-y-z.md`) to the `/site_collections/_posts/` folder
+	- In the post, change the relevant info in both the file name (i.e. rename the file following the `yyyy-mm-dd-release-x-y-z` name format) and the front matter section.
+	- Most of the body text can be copied from the GitHub `CHANGELOG.md`, please include any extra information about the release before the "Major Changes" section.
+3. Change the download links by setting the variables in `_config.yml`:
+	- Ensure that the release information entered is the same as the **latest release** on GitHub, i.e. the release linked to [releases/latest](https://github.com/NatronGitHub/Natron/releases/latest)
+	- Under the `natron` field:
+		- Set the branch to the latest release's branch name (at the moment, however, this is a semi-redundant field that we don't use for anything)
+		- Set `version` to the version number **set in the Github release**. This should **always** be in X.Y.Z format (e.g. 2.5.0, 2.4.3, etc.)
+		- Set `date` to the release date in `YYYY-MM-DD` format
+	- All the other variables will be under the `downloads` field (which is at the top of the `_config.yml`)
+		- We assume that release binaries follow the general format `Natron-<VERSION><BUILDNAME>` except for non-GitHub distribution channels (as of the moment, the only one is Flatpak and that shouldn't need to be changed anyways). For all other (i.e. GitHub-based) distribution channels, the `url` fields _must_ be left blank.
+		- The `suffix` fields for all the downloads provide the `<BUILDNAME>` mentioned above for each of the different platforms
+		- In theory there should be no need to touch any of the `suffix` fields unless there is a major naming convention change in the build scripts. Changing the **version, date, and branch** should be **the only changes required** for every new release.
+		- In addition to macOS, Windows, and Linux, the `other` field contains download links for alternate distribution channels and for non-binary downloads (though again, these links probably don't need to be changed, at least not often). New links can be freely added to this section, but **don't** remove any existing links or change their associated variable names.
+	- In general: unless if there is a specific reason, it is advisable to only change the variable _values_, not the variable names, as doing otherwise will require a change in the templates. In particular, the categories for Windows, macOS, and Linux should stay as-is, please **only** change the values and do _not_ rename the fields/remove any fields within those categories unless you know what you are doing.
+4. **Test out the site locally first** by running the live server with `bundle exec jekyll serve` (following instructions as given above), then publish to main!
 
 ## Licensing
 

diff --git a/_config.yml b/_config.yml
@@ -13,7 +13,7 @@ facebook: https://facebook.com/groups/NatronNation/
 
 # Values to change when setting up a new Natron release
 natron:
-  branch: 2.5
+  branch: RB-2.5
   release:
     version: 2.5.0
     date: "2022-11-25"
@@ -61,6 +61,7 @@ downloads:
         url: ""
         suffix: "-OSX-Universal.dmg"
   other:
+    silicon-prerelease: https://github.com/NatronGitHub/Natron/releases/tag/v2.6.0-alpha1
     freshports: https://www.freshports.org/graphics/natron/
     examples: https://sourceforge.net/projects/natron/files/Examples/
     natron-plugins: https://github.com/NatronGitHub/natron-plugins

diff --git a/_sass/_index.scss b/_sass/_index.scss
@@ -173,6 +173,21 @@
   }
 }
 
+.index-downloads-extrainfo {
+    margin-top: 4rem;
+    margin-left: auto;
+    margin-right: auto;
+    max-width: 40ch;
+    text-align: center;
+
+    p.p-small {
+      font-size: smaller;
+      color: var(--grey);
+      margin-left: auto;
+      margin-right: auto;
+    }    
+}
+
 .index-downloads-other {
   margin-top: 4rem;
 

diff --git a/about.md b/about.md
@@ -7,9 +7,9 @@ title: About Natron
 
 ![An animated cartoon shot open in Natron](img/about-screenshot.png)
 
-## Cross-platform open-source compositor for the visual effects industry
+## Cross-platform open-source compositor for the VFX industry
 
-Natron is a powerful free and open-source VFX compositor geared towards digital post-production work, with industry-standard UI, 100+ nodes, and support for OpenFX and community-made plugins. With its robust OpenFX based engine and support for OpenImageIO and OpenColorIO, Natron can handle all of your VFX post-production needs.
+Natron is a powerful, free, and open-source VFX compositing application geared towards digital post-production work.  Natron sports a familiar UI, over 100 nodes, and support for OpenFX and community-made plugins. With its robust OpenFX-based engine and support for OpenImageIO and OpenColorIO, Natron can handle all of your VFX post-production needs.
 
 Natron was a proud recipient of [Inria](https://www.inria.fr/en) funding from 2013–2018, and is currently being developed by a team of open-source contributors as a community effort.
 
@@ -29,7 +29,7 @@ Yes, Natron is free software. Free to use, free to modify, and free to share, du
 
 ### What can Natron do?
 
-Natron is a powerful digital compositor capable of handling a multitude of VFX and post-production tasks. Natron's capabilities include but are not limited to:
+Natron is a powerful digital compositor capable of handling a multitude of VFX and post-production tasks. Natron's capabilities include (but are not limited to):
 
 - Linear node-based workflow
 - 32bit/channel floating-point linear processing pipeline
@@ -41,7 +41,7 @@ Natron is a powerful digital compositor capable of handling a multitude of VFX a
 - Extensive OpenFX and community plugins support
 - And much more!
 
-Natron can be used in conjunction with [Blender](https://www.blender.org/) to extend it's capabilities by utilising Blender's 3D environment. This is facilitated by Natron's support for CHAN files for transferring camera tracking data.
+While Natron **does not yet have a 3D workspace**, it can be used in conjunction with [Blender](https://www.blender.org/) to extend its capabilities by utilizing Blender's 3D environment. Natron additionally supports CHAN files for transferring camera tracking data.
 
 ### Does the Natron Project accept donations?
 

diff --git a/index.html b/index.html
@@ -108,7 +108,7 @@ <h2 class="h2 center-text">Download Natron</h2>
     <div class="index-downloads-oscontainer">
       <div class="index-downloads-os">
         <div>
-          <h3 class="h3"><i class='bx bxl-apple'></i>macOS</h3>
+          <h3 class="h3"><i class='bx bxl-apple'></i>macOS (Intel only)*</h3>
         </div>
         <div>
           <p class="p-small">
@@ -158,9 +158,13 @@ <h3 class="h3"><i class='bx bxl-tux'></i>GNU/Linux</h3>
         </div>
       </div>
     </div>
+    <div class="index-downloads-extrainfo">
+      <p class="p-small center-text">* The latest stable release runs on Apple Silicon Macs via Rosetta 2. A <a href="{{ site.downloads.other.silicon-prerelease }}" class="intext-link intext-link-glow">beta build with native support for Apple Silicon</a> is available for those who'd like to try it!</p>
+    </div>
     <div class="index-downloads-other">
       <h4 class="h4 center-text">Other Downloads:</h4>
       <p class="p-small center-text">
+        <a href="https://github.com/NatronGitHub/Natron/releases/" class="intext-link intext-link-glow">Past Releases</a>
         <a href="{{ site.downloads.other.freshports }}" class="intext-link intext-link-glow">FreeBSD: Freshports</a>
         <a href="{{ site.downloads.other.examples }}" class="intext-link intext-link-glow">Sample projects</a>
         <a href="{{ site.downloads.other.natron-plugins }}" class="intext-link intext-link-glow">Community Plugins</a>