This document talks about how Contributors can work on authoring their material. The next document in this series discusses how to publish those changes to the ProjectLiberty2029 repository.
There are two ways for Contributors to work with this project’s files.
What you will notice working in GitHub on the Website interface, is that every time you want to "save" a document, you must "Commit Changes" and give a text explanation of what you were changing.
This method is perfect for one-file changes: if you want to fix or extend a document that already exists, or you want to propose a new document. Even if a document is "complicated," as long as it’s a single document, this is a fine method.
If you believe you will be many sessions in writing the file, then it is probably best to write it in a text-editor. Asciidoctor :has a page that discusses some of these." There is also a tool called Brackets.
But it may be the best option, since we are also on GitHub, which integrates with VS Code to use the VS Code editor.
We recommend learning VS Code because it integrates best with GitHub and has more support. But at this time, we do not yet have documentation for setting it up. There are online tutorials, on and perhaps if you are interested, you could write the guide.
(Asciidoc has a page dedicated to other editors and viewers for Asciidoc, many much more powerful than Brackets, but most requiring some additional level of expertise to setup.)
If you work in GitHub Desktop, you will be able to simultaneously change many files, and save them without making a commit. On GitHub Desktop, when you’re ready with all your changes, you make a single "commit" for all those changes together.
This method is the best one for making a series of changes, or if you will be a frequent contributor, because it lets you save a local copy of your work and make as many iterations to as many files as you like before sending a coherent and complete package to be merged into the main repository.
This method works best in conjunction with an editor called VS Code (which stands for "Visual Studio" Code, which is a Microsoft project.) VS Code is the most widely used editing program for software in the world. It has modular plugins for every computing language in the world as well. For ProjectLiberty2029, I, Vector Hasting, am using the "Asciidoc by asciidoctor" extension. It allows VS Code to edit-check the asciidoc syntax as I write it. It also gives me the option of previewing the webpage inside VS Code, though I generally use a jekyll environment to do that. We will have more complete instructions on these tools later in this document, though as of this draft of this document, those tools are not explained.
There is a A Sample Document to Copy and Modify. which is meant to give you something to cut-and-paste the asciidoc bits you will need, so that you can concentrate on writing.
If you have additional asciidoc questions, the official documentation is here. However, it is often more helpful to online-search for the thing you want in the form of "give me an example of how to do xyz in asciidoc."
As we gather a community, there is also our subreddit for discussion and support. and our GitHub discussions board.
There is an online converter that attempts to convert Word documents to Asciidoc, but results require fixing up.
Note: there are many possible work-flows on GitHub, or any other git-enabled repository.
For basic changes, like adding a single page or fixing minor typos, it is perhaps easiest to work straight in the GitHub Website interface.
You will need to navigate to the GitHub Website for Project Liberty 2029.
Find the button near the top right that says "Fork," click it and follow the instructions to create your own copy of ProjectLiberty2029.github.io.
Switch to that repository: this can be confusing at first:
the original is "https://github.com/ProjectLiberty2029/ProjectLiberty2029.github.io,"
but yours will be "https://github.com/YourUserName/ProjectLiberty2029.github.io."
(The reason we need to use this "fork-and-merge" technique is to satisfy our Clarity and Security requirements which are explored in Overview of the Environment.
Note: there are many possible work-flows on GitHub, or any other git-enabled repository.
Here is the collection of Contributing docs. Feel free to contribute to Contributing!
Adding and Editing Pages on GitHub. (This document.)
There is also a subreddit for discussion and support.
We also have a discussions area on GitHub itself.
|
All documents formatted and/or identified as Legislation are hereby donated to the public domain. |
