From 43a99a4d4be8586fa2d35de9cd8a41925fad240e Mon Sep 17 00:00:00 2001 From: freesky-edward Date: Tue, 27 Aug 2019 18:07:32 +0800 Subject: [PATCH] Add doc guide adding news content --- CONTRIBUTING.md | 83 +++++++++++++++++++++++++++++++++++++++++++++ docs/adding-news.md | 65 +++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 docs/adding-news.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..26e7d1c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,83 @@ +# How to contribute + +## Report issues + +A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate a well-written, thorough bug report and feature propose, and will thank you for it! + +### Issues format + +When reporting issues, refer to this format: + +- Is this a BUG REPORT or FEATURE REQUEST? +- What happened? +- What you expected to happen? +- What happened? +- How to reproduce it (as minimally and precisely as possible) +- Anything else we need to know? +- Environment + +See more about [ISSUE_TEMPLATE](.github/ISSUE_TEMPLATE.md). + +## Submit pull requests + +If you are a beginner and expect this project as the gate to open source world, this tutorial is one of the best +choices for you. Just follow the guidance and you will find the pleasure to becoming a contributor. + +### Step 1: Fork repository + +Before making modifications of this project, you need to make sure that this project have been forked to your own +repository. It means that there will be parallel development between this repo and your own repo, so be careful +to avoid the inconsistency between these two repos. + +### Step 2: Clone the remote repository + +If you want to download the code to the local machine, ```git``` is the best way: +``` +git clone https://your_repo_url/projectname.git +``` + +### Step 3: Develop code locally + +To avoid inconsistency between multiple branches, we SUGGEST checking out to a new branch: +``` +git checkout -b new_branch_name origin/master +``` +Then you can change the code arbitrarily. + +### Step 4: Push the code to the remote repository + +After updating the code, you should push the update in the formal way: +``` +git add . +git status (Check the update status) +git commit -m "Your commit title" +git commit --amend (Add the concrete description of your commit) +git push origin new_branch_name +``` + +### Step 5: Pull a request to repository + +In the last step, your need to pull a compare request between your new branch and development branch. After +finishing the pull request, the CI will be automatically set up for building test. + +### Pull requests format + +When submitting pull requests, refer to this format: + +- What this PR does / why we need it? +- Which issue this PR fixes? +- Special notes for your reviewer +- Release note + +See more about [PULL_REQUEST_TEMPLATE](.github/PULL_REQUEST_TEMPLATE.md). + +### Code style + +```TO BE DEFINED``` + + + + + + + diff --git a/docs/adding-news.md b/docs/adding-news.md new file mode 100644 index 0000000..3be6727 --- /dev/null +++ b/docs/adding-news.md @@ -0,0 +1,65 @@ +## Brief + +This doc will guide anyone who is going to add/modify the news content in our website. all workflow will follow the PR flow. please refer to [CONTRIBUTING](../CONTRIBUTING.md) for deep guiding if you are not fimiliar to how to submit a PR. + +All contents in this website are written in Markdown syntax. if you are beginner to Mardown, [Tutorial](https://www.markdowntutorial.com/) would be a good start to you. for news, it also write in markdown with a special header definition. + +### Content & Structure + +A news contains following parties, we strongly recommend you prepare all of these items without any blank: + +- banner: An image reprents the ocurring sinario will be showed as a header in news list page. we recommend to use standard size with 1000*750 for better showing. +- title: The brief introduction of the new +- description: A more detailed introduction than title for the news. +- author: who provides the news content. +- categories: the category where user can find it easily. +- date: the news ocurring time. +- content: the detailed introduction for the stroy. + +All above content except banner image will be defined in one file under ```content/``` folder with Markdown syntax but banner image content should be submitted into ```static/img/``` folder and defined in the file. as multilingual content supported now, so please check which language are you going to add in, this will decide which sub-folder under ```content``` will be choosed. e.g. ```content/en```, ```content/zh``` or other further languages supported. the final path where the file would be located is ```content//news```. + +so, the folder structure would be: + +|__content/en/news/my-news.md +|__static/img/my-news-banner.png + +Note: content file must locates under ```news``` folder. however banner iamge can locates whatever sub-dir you want, but be sure you have configuration the path correctly. please step to next section for more file style. + +### Header definition + +A news file content two parties, one is the header configuration, another is the content. the header definition starts and end with ```+++``` or ```---```. Note: the sign number must be ***3***. e.g. + ++++ +title = "openEuler community meetup held in Shanghai" +date = "2019-10-10T13:50:46+02:00" +categories = ["meetup"] +author = "openEuler" +description = "The first meetup held in shanghai, there are more 500+ attenders joined this meetup." +banner = "img/banners/banner-1.jpg" ++++ + +Note: +- banner: a path starts with ```img```. +- categories: mutil-value supports, this value is a list of strings, echo one is a category. +- date: we recommend flowing the example style. + +the remain content following the header definition is the news characters. + +### Example + ++++ +title = "openEuler community meetup held in Shanghai" +date = "2019-10-10T13:50:46+02:00" +categories = ["meetup"] +author = "openEuler"description = "The first meetup held in shanghai, there are more 500+ attenders joined this meetup." +banner = "img/banners/banner-1.jpg" ++++ + + +10th, Oct, 2019. openEuler held the first meetup in Shanghai, China. the chairman Mr.Li has a wonderful speech and give us a good blueprint that openEuler will reach out..... + + + + + + -- GitLab