From 1bf94d0eed3c186692269e4907f2f920a1114250 Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Tue, 21 Apr 2020 18:18:20 +0100 Subject: README-hacking.md: minor clarifications in checklist Roberto Baena recently tried building a new project with Maneage and provided the following suggestions to make it more clear for a new user: 1) In the part where we talk about creating a Git repository, we should highlight that it must be empty. This is because some (for example Gitlab) propose to include a `README' file. But if the project is not empty, Git will not allow pushing to it. 2) The `(can be done later)' comment was removed from the "Delete dummy parts") to avoid confusion about applying some of them, but not others: if only some are done, it may cause problems in the build. --- README-hacking.md | 60 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/README-hacking.md b/README-hacking.md index 9be0c61..357e981 100644 --- a/README-hacking.md +++ b/README-hacking.md @@ -588,17 +588,19 @@ First custom commit perfect)](https://www.gnu.org/software/repo-criteria-evaluation.html), and later you can also host GitLab on your own server. Anyway, create an account in your favorite hosting facility (if you don't already - have one), and define a new project there. It will give you a URL - (usually starting with `git@` and ending in `.git`), put this URL in - place of `XXXXXXXXXX` in the first command below. With the second - command, "push" your `master` branch to your `origin` remote, and - (with the `--set-upstream` option) set them to track/follow each - other. However, the `maneage` branch is currently tracking/following - your `origin-maneage` remote (automatically set when you cloned - Maneage). So when pushing the `maneage` branch to your `origin` - remote, you _shouldn't_ use `--set-upstream`. With the last command, - you can actually check this (which local and remote branches are - tracking each other). + have one), and define a new project there. Please make sure *the newly + created project is empty* (some services ask to include a `README` in + a new project which is bad in this scenario, and will not allow you to + push to it). It will give you a URL (usually starting with `git@` and + ending in `.git`), put this URL in place of `XXXXXXXXXX` in the first + command below. With the second command, "push" your `master` branch to + your `origin` remote, and (with the `--set-upstream` option) set them + to track/follow each other. However, the `maneage` branch is currently + tracking/following your `origin-maneage` remote (automatically set + when you cloned Maneage). So when pushing the `maneage` branch to your + `origin` remote, you _shouldn't_ use `--set-upstream`. With the last + command, you can actually check this (which local and remote branches + are tracking each other). ```shell git remote add origin XXXXXXXXXX # Newly created repo is now called 'origin'. @@ -617,21 +619,23 @@ First custom commit your own methods after finishing this checklist and doing your first commit. - 6. **Delete dummy parts (can be done later)**: Maneage contains some parts - that are only for the initial/test run, mainly as a demonstration of - important steps. They not for any real analysis. You can remove these - parts in the file below + 6. **Delete dummy parts**: Maneage contains some parts that are only for + the initial/test run, mainly as a demonstration of important steps, + which you can use as a reference to use in your own project. But they + not for any real analysis, so you should remove these parts as + described below: - `paper.tex`: 1) Delete the text of the abstract (from - `\includeabstract{` to `\vspace{0.25cm}`) and start writing your own - (a single sentence can be enough now). 2) Add some keywords under it - in the keywords part. 3) Delete everything between `%% Start of main - body.` and `%% End of main body.`. 4) Remove the notice in the - "Acknowledgments" section (in `\new{}`) and add Acknowledge your - funding sources. Just don't delete the existing acknowledgment - statement: Maneage was designed by funding from many grants. Since - you are using it in your work, it is necessary to acknowledge them - in your work also. + `\includeabstract{` to `\vspace{0.25cm}`) and write your own own (a + single sentence can be enough now, you can complete it later). 2) + Add some keywords under it in the keywords part. 3) Delete + everything between `%% Start of main body.` and `%% End of main + body.`. 4) Remove the notice in the "Acknowledgments" section (in + `\new{}`) and Acknowledge your funding sources (this can also be + done later). Just don't delete the existing acknowledgment + statement: Maneage is possible thanks to funding from several + grants. Since Maneage is being used in your work, it is necessary to + acknowledge them in your work also. - `reproduce/analysis/make/top-make.mk`: Delete the `delete-me` line in the `makesrc` definition. Just make sure there is no empty line @@ -674,10 +678,10 @@ First custom commit the first `echo` command has a `>` (to re-write the file with the given line), the rest are `>>` (to append to it). After doing this step in your own branch, when future commits in Maneage make any - change in the given files, they will not be imported into your - project's branch (it can be annoying!). You can follow a similar - strategy if you want to avoid any other set of files to be imported - from Maneage into your project's branch. + change in these files, it will not cause a conflict with your + project when you update Maneage (it is annoying!). You can follow a + similar strategy if you want to avoid any other set of files to be + imported from Maneage into your project's branch. ```shell $ echo "paper.tex" > .gitattributes -- cgit v1.2.1